SALE request
Payment Platform supports two main operation type: Single Message System (SMS) and Dual Message System (DMS).
SMS is represented by SALE transaction. It is used for authorization and capture at a time. This operation is commonly used for immediate payments.
DMS is represented by AUTH and CAPTURE transactions. AUTH is used for authorization only, without capture. This operation used to hold the funds on card account (for example to check card validity).
SALE request is used to make both SALE and AUTH transactions.
If you want to make AUTH transaction, you need to use parameter auth with value Y. If you want to send a payment for the specific sub-account (channel), you need to use channel_id, that specified in your Payment Platform account settings.
This request is sent by POST in the background (eg, through PHP CURL).
Request parameters
Parameter | Description | Values | Required field |
action | Sale | SALE | + |
async | Asynchronous or synchronous mode | Y or N (default N) | – |
client_key | Unique client key (CLIENT_KEY) | + | |
channel_id | Payment channel (Sub-account) | String up to 16 characters | – |
order_id | Transaction ID in the Clients system | String up to 255 characters | + |
order_amount | The amount of the transaction | Numbers in the form XXXX.XX (without leading zeros) |
+ |
order_currency | Currency | 3-letter code | + |
order_description | Description of the transaction (product name) | String up to 1024 characters | + |
req_token | Special attribute pointing for further tokenization | Y or N (default N) | – |
gpay_token | Token received by a merchant from Google | Y or N (default N) | – |
card_token | Credit card token value | String 64 characters | – |
card_number | Credit Card Number | +1 | |
card_exp_month | Month of expiry of the credit card | Month in the form XX | +1 |
card_exp_year | Year of expiry of the credit card | Year in the form XXXX | +1 |
card_cvv22 | CVV/CVC2 credit card verification code | 3-4 symbols | +1 |
payer_first_name | Customer’s name | String up to 32 characters | + |
payer_last_name | Customer’s surname | String up to 32 characters | + |
payer_middle_name | Customer’s middle name | String up to 32 characters | + |
payer_birth_date | Customer’s birthday | format yyyy-MM-dd, e.g. 1970-02-17 | + |
payer_address | Customer’s address | String up to 255 characters | + |
payer_address2 | The adjoining road or locality (if required) of the сustomer’s address | String up to 255 characters | + |
payer_country | Customer’s country | 2-letter code | + |
payer_state | Customer’s state | String up to 32 characters | + |
payer_city | Customer’s city | String up to 32 characters | + |
payer_zip | ZIP-code of the Customer | String up to 32 characters | + |
payer_email | Customer’s email | String up to 256 characters | + |
payer_phone | Customer’s phone | String up to 32 characters | + |
payer_ip | IP-address of the Customer | XXX.XXX.XXX.XXX | + |
term_url_3ds | URL to which Customer should be returned after 3D-Secure | String up to 1024 characters | + |
recurring_init | Initialization of the transaction with possible following recurring | Y or N (default N) | – |
ext1 | Client Parameter 1 | – | |
ext… | Client Parameter … | – | |
ext10 | Client Parameter 10 | – | |
auth | Indicates that transaction must be only authenticated, but not captured | Y or N (default N) | – |
hash | Special signature to validate your request to Payment Platform | * (Appendix A) | + |
1 – This field becomes optional if card_token is specified
2 – This field becomes optional if acquirer handles non-CVV2 transactions
If the optional parameter card_token and card data are specified, card_token will be ignored. If the optional parameters req_token and card_token are specified, req_token will be ignored.
If the optional parameters gpay token = Y, fields: card_number, card_exp_month, card_exp_year, card_cvv2 will be not required.
Response parameters
You will get JSON encoded string (see an example on Appendix B) with transaction result. If your account supports 3D-Secure, transaction result will be sent to your Callback URL.
Synchronous mode
Successful sale response:
Parameter | Description |
action | SALE |
result | SUCCESS |
status | PENDING/SETTLED; only PENDING when auth=Y |
order_id | Transaction ID in the Client’s system |
trans_id | Transaction ID in the Payment Platform |
trans_date | Transaction date in the Payment Platform |
descriptor | This is a string which the owner of the credit card will see in the statement from the bank. In most cases, this is the Customers support web-site. |
recurring_token | Recurring token (get if account support recurring sales and was initialization transaction for following recurring) |
amount | Order amount |
currency | Currency |
card_token | If the parameter req_token was enabled Payment Platform returns the token value |
Unsuccessful sale response:
Parameter | Description |
action | SALE |
result | DECLINED |
status | DECLINED |
order_id | Transaction ID in the Client’s system |
trans_id | Transaction ID in the Payment Platform |
trans_date | Transaction date in the Payment Platform |
decline_reason | The reason why the transaction was declined |
3D-Secure transaction response:
Parameter | Description |
action | SALE |
result | REDIRECT |
status | 3DS |
order_id | Transaction ID in the Client’s system |
trans_id | Transaction ID in the Payment Platform |
trans_date | Transaction date in the Payment Platform |
redirect_url | URL to which the Client should redirect the Customer |
redirect_params | Array of specific 3DS parameters |
redirect_method | The method of transferring parameters (POST/GET) |
Asynchronous mode
If you want to use asynchronous mode, you need to use async parameter with value “Y” in your sale request.
Using this mode you will get synchronous response (JSON encoded string) below that transaction is accepted for processing and result will be sent to your Callback URL.
Parameter | Description |
action | SALE |
result | ACCEPTED |
order_id | Transaction ID in the Client’s system |
trans_id | Transaction ID in the Payment Platform |
trans_date | Transaction date in the Payment Platform |
Callback parameters
Successful sale response:
Parameter | Description |
action | SALE |
result | SUCCESS |
status | PENDING/SETTLED |
order_id | Transaction ID in the Client’s system |
trans_id | Transaction ID in the Payment Platform |
trans_date | Transaction date in the Payment Platform |
descriptor | This is a string which the owner of the credit card will see in the statement from the bank. In most cases, this is the Customers support web-site. |
auth_code | Bank approval code |
recurring_token | Recurring token (get if account support recurring sales and was initialization transaction for following recurring) |
amount | Order amount |
currency | Currency |
card_token | If the parameter req_token was enabled Payment Platform returns the token value |
hash | Special signature, used to validate callback **(Appendix A) |
Unsuccessful sale response:
Parameter | Description |
action | SALE |
result | DECLINED |
status | DECLINED |
order_id | Transaction ID in the Client’s system |
trans_id | Transaction ID in the Payment Platform |
trans_date | Transaction date in the Payment Platform |
decline_reason | Description of the cancellation of the transaction |
hash | Special signature, used to validate callback **(Appendix A) |
3D-Secure transaction response:
Parameter | Description |
action | SALE |
result | REDIRECT |
status | 3DS |
order_id | Transaction ID in the Client’s system |
trans_id | Transaction ID in the Payment Platform |
trans_date | Transaction date in the Payment Platform |
redirect_url | URL to which the Client should redirect the Customer |
redirect_params | Array parameters |
redirect_method | The method of transferring parameters (POST/GET) |
hash | Special signature, used to validate callback **(Appendix A) |