1. Introduction
This document describes integration procedures and POST protocol usage for ecommerce merchants.
POST protocol implements acquiring payments (purchases) using specific API interaction.
2. Integration process
2.1 Client registration
Before you get an account to access Payment Platform, you must provide the following data to the Payment Platform administrator.
| IP list | List of your IP addresses, from which requests to Payment Platform will be sent. |
| Callback URL | URL which will be receiving the notifications of the processing results of your request to Payment Platform. |
| Contact email | Client’s contact email |
Note: Callback URL is mandatory if you work in asynchronous mode, or if your account supports 3D-Secure. The length of Callback URL shouldn’t be more than 255 symbols.
With all Payment Platform POST requests at Callback URL the Client must return the string “OK” if he successfully received data or return “ERROR”.
You should get the following information from administrator to begin working with the Payment Platform.
| CLIENT_KEY | Unique key to identify the account in Payment Platform (used as request parameter) |
| CLIENT_PASS | Password for Client authentication in Payment Platform (used for calculating hash parameter) |
| PAYMENT_URL | URL to request the Payment Platform |
2.2 Brief description of the interaction with Payment Platform
1. For the transaction, you must send the server to server HTTPS POST request with fields listed below to Payment Platform URL (PAYMENT_URL). In response Payment Platform will return the JSON (https://json.org/) encoded string.
2. If your account supports 3D-Secure and credit card supports 3D-Secure, then Payment Platform will return the link to the 3D-Secure Access Control Server to perform 3D-Secure verification. In this case, you need to redirect the card-holder at this link. If there are also some parameters except the link in the result, you will need to redirect the cardholder at this link together with the parameters using the method of data transmitting indicated in the same result.
3. In the case of 3D-Secure after verification on the side of the 3D-Secure server, the owner of a credit card will come back to your site using the link you specify in the sale request, and Payment Platform will return the result of transaction processing to the Callback URL action.
2.3 List of possible actions in Payment Platform
When you make request to Payment Platform, you need to specify action, that needs to be done. Possible actions are:
| Action | Description |
|---|---|
| SALE | Creates SALE or AUTH transaction |
| CAPTURE | Creates CAPTURE transaction |
| CREDITVOID | Creates REVERSAL or REFUND transaction |
| GET_TRANS_STATUS | Gets status of transaction in Payment Platform |
| GET_TRANS_DETAILS | Gets details of the order from Payment platform |
| RECURRING_SALE | Creates SALE transaction using previously used cardholder data |
| SCHEDULE | Creates schedule for recurring transactions |
| DESCHEDULE | Disables schedule for recurring transactions |
Following actions can’t be made by request, they’re created by Payment Platform in certain circumstances (e.g. issuer initiated chargeback) and you receive callback as a result.
| Action | Description |
|---|---|
| CHARGEBACK | CHARGEBACK transaction was created in Payment Platform |
| CHARGEBACK_REVERSAL | CHARGEBACK_REVERSAL transaction was created in Payment Platform |
| SECOND_PRESENTMENT | SECOND_PRESENTMENT transaction was created in Payment Platform |
| SECOND_PRESENTMENT_REVERSAL | SECOND_PRESENTMENT_REVERSAL transaction was created in Payment Platform |
| SECOND_CHARGEBACK | SECOND_CHARGEBACK transaction was created in Payment Platform |
| SECOND_CHARGEBACK_REVERSAL | SECOND_CHARGEBACK_REVERSAL transaction was created in Payment Platform |
| ARBITRATION | ARBITRATION transaction was created in Payment Platform |
| ARBITRATION_REVERSAL | ARBITRATION_REVERSAL transaction was created in Payment Platform |
| ARBITRATION_WON | ARBITRATION_WON transaction was created in Payment Platform |
| ARBITRATION_LOST | ARBITRATION_LOST transaction was created in Payment Platform |
2.4 List of possible transaction results and statuses
Result – value that system returns on request. Possible results are:
| Result | Description |
|---|---|
| SUCCESS | Action was successfully completed in Payment Platform |
| DECLINED | Result of unsuccessful action in Payment Platform |
| REDIRECT | Additional action required from requester. (Redirect to 3ds) |
| ACCEPTED | Action was accepted by Payment Platform, but will be completed later. |
| ERROR | Request has errors and was not validated by Payment Platform |
Status – actual status of transaction in Payment Platform. Possible statuses are:
| Status | Description |
|---|---|
| 3DS | The transaction awaits 3D-Secure validation |
| PENDING | The transaction awaits CAPTURE |
| SETTLED | Successful transaction |
| REVERSAL | Transaction for which reversal was made |
| REFUND | Transaction for which refund was made |
| CHARGEBACK | Transaction for which chargeback was made |
| CHARGEBACK_REVERSAL | Transaction for which chargeback reversal was made |
| SECOND_PRESENTMENT | Transaction for which second presentment was made |
| SECOND_PRESENTMENT_REVERSAL | Transaction for which second presentment reversal was made |
| SECOND_CHARGEBACK | Transaction for which second chargeback was made |
| SECOND_CHARGEBACK_REVERSAL | Transaction for which second chargeback reversal was made |
| ARBITRATION | Transaction for which Arbitration was made |
| ARBITRATION_REVERSAL | Transaction for which Arbitration reversal was made |
| ARBITRATION_WON | Transaction for which Arbitration was won |
| ARBITRATION_LOST | Transaction for which Arbitration was lost |
| DECLINED | Not successful transaction |
3. Card transactions requests
3.1 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) | – |
| card_token | Credit card token value | String 64 characters | – |
| card_number | Credit Card Number | +¹ | |
| card_exp_month | Month of expiry of the credit card | Month in the form XX | +¹ |
| card_exp_year | Year of expiry of the credit card | Year in the form XXXX | +¹ |
| card_cvv2² | CVV/CVC2 credit card verification code | 3-4 symbols | +¹ |
| payer_first_name | Customer’s name | String up to 32 characters | + |
| payer_last_name | Customer’s surname | String up to 32 characters | + |
| payer_address | Customer’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) | – |
| 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.
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) |
3.2 CAPTURE request
CAPTURE request is used to submit previously authorized transaction (created by AUTH request). Hold funds will be transferred to Merchants account.
This request is sent by POST in the background (eg, through PHP CURL).
Request parameters
| Parameter | Description | Values | Required field |
|---|---|---|---|
| action | Capture previously authenticated transaction | CAPTURE | + |
| client_key | Unique client key (CLIENT_KEY) | + | |
| trans_id | Transaction ID in the Payment Platform | String up to 255 characters | + |
| amount | The amount for partial capture. Only one partial capture allowed. | Numbers in the form XXXX.XX (without leading zeros) | – |
| hash | Special signature to validate your request to payment platform | **(Appendix A) | + |
Response parameters
Successful capture response:
| Parameter | Description |
|---|---|
| action | CAPTURE |
| result | SUCCESS |
| status | SETTLED |
| amount | Amount of capture. |
| order_id | Transaction ID in the Client’s system |
| trans_id | Transaction ID in the Payment Platform |
Unsuccessful capture response:
| Parameter | Description |
|---|---|
| action | CAPTURE |
| result | DECLINED |
| status | PENDING |
| order_id | Transaction ID in the Client’s system |
| trans_id | Transaction ID in the Payment Platform |
| decline_reason | The reason why the capture was declined |
Callback parameters
Successful capture response:
| Parameter | Description |
|---|---|
| action | CAPTURE |
| result | SUCCESS |
| status | SETTLED |
| order_id | Transaction ID in the Client’s system |
| trans_id | Transaction ID in the Payment Platform |
| amount | Amount of capture. |
| hash | Special signature, used to validate callback **(Appendix A) |
Unsuccessful capture response:
| Parameter | Description |
|---|---|
| action | CAPTURE |
| result | DECLINED |
| status | PENDING |
| order_id | Transaction ID in the Client’s system |
| trans_id | Transaction ID in the Payment Platform |
| decline_reason | The reason why the capture was declined |
| hash | Special signature, used to validate callback **(Appendix A) |
3.3 CREDITVOID request
CREDITVOID request is used to complete both REFUND and REVERSAL transactions.
REVERSAL transaction is used to cancel hold from funds on card account, previously authorized by AUTH transaction.
REFUND transaction is used to return funds to card account, previously submitted by SALE or CAPTURE transactions.
This request is sent by POST in the background (eg, through PHP CURL).
Request parameters
| Parameter | Description | Values | Required field |
|---|---|---|---|
| action | CREDITVOID | CREDITVOID | + |
| client_key | Unique client key (CLIENT_KEY) | + | |
| trans_id | Transaction ID in the Payment Platform | String up to 255 characters | + |
| amount | The amount for partial refund. Several partial refunds allowed. | Numbers in the form XXXX.XX (without leading zeros) | – |
| hash | Special signature to validate your request to Payment Platform | **(Appendix A) | + |
Response parameters
| Parameter | Description |
|---|---|
| action | CREDITVOID |
| result | ACCEPTED |
| order_id | Transaction ID in the Client’s system |
| trans_id | Transaction ID in the Payment Platform |
Callback parameters
Successful refund/reversal response
| Parameter | Description |
|---|---|
| action | CREDITVOID |
| result | SUCCESS |
| status | REFUND/REVERSAL |
| order_id | Transaction ID in the Client system |
| trans_id | Transaction ID in the Payment Platform |
| creditvoid_date | Date of the refund/reversa |
| trans_id | Transaction ID in the Payment Platform |
| amount | Amount of refund. |
| hash | Special signature, used to validate callback**(Appendix A) |
Unsuccessful refund/reversal response
| Parameter | Description |
|---|---|
| action | CREDITVOID |
| result | DECLINED |
| order_id | Transaction ID in the Client system |
| trans_id | Transaction ID in the Payment Platform |
| decline_reason | Description of the cancellation of the transaction |
| hash | Special signature, used to validate callback **(Appendix A) |
3.4 GET_TRANS_STATUS request
Gets order status from Payment Platform. This request is sent by POST in the background (eg, through PHP CURL).
Request parameters
| Parameter | Description | Values | Required field |
|---|---|---|---|
| action | GET_TRANS_STATUS | GET_TRANS_STATUS | + |
| client_key | Unique client key (CLIENT_KEY) | + | |
| trans_id | Transaction ID in the Payment Platform | String up to 255 characters | + |
| hash | Special signature to validate your request to Payment Platform | **(Appendix A) | + |
Response parameters
| Parameter | Description |
|---|---|
| action | GET_TRANS_STATUS |
| result | SUCCESS |
| status | 3DS / PENDING / DECLINED / SETTLED / REVERSAL / REFUND / CHARGEBACK / SECOND_PRESENTMENT / SECOND_CHARGEBACK, ARBITRATION |
| order_id | Transaction ID in the Client’s system |
| trans_id | Transaction ID in the Payment Platform |
3.5 GET_TRANS_DETAILS request
Gets all history of transactions by the order. This request is sent by POST in the background (eg, through PHP CURL).
Request parameters
| Parameter | Description | Values | Required field |
|---|---|---|---|
| action | GET_TRANS_DETAILS | GET_TRANS_DETAILS | + |
| client_key | Unique client key (CLIENT_KEY) | + | |
| trans_id | Transaction ID in the Payment Platform | String up to 255 characters | + |
| hash | Special signature to validate your request to Payment Platform | **(Appendix A) | + |
Response parameters
| Parameter | Description |
|---|---|
| action | GET_TRANS_DETAILS |
| result | SUCCESS |
| status | 3DS / PENDING / DECLINED / SETTLED / REVERSAL / REFUND / CHARGEBACK / SECOND_PRESENTMENT / SECOND_CHARGEBACK, ARBITRATION |
| order_id | Transaction ID in the Client’s system |
| trans_id | Transaction ID in the Payment Platform |
| name | Payer name |
| Payer mail | |
| ip | Payer IP |
| amount | Order amount |
| currency | Currency |
| card | Card in the format XXXXXX****XXXX |
| transactions² | Array of transactions |
2 – In the array each of transactions has: date, type, status (0-fail, 1-success) and amount. For example:
{"transactions":[
{"date":"2012-01-01 01:10:25","type":"AUTH","status":"1","amount":"1.95"},
{"date":"2012-01-01 01:11:30","type":"CAPTURE","status":"1","amount":"1.95"},
{"date":"2012-02-06 10:25:06","type":"REFUND","status":"1","amount":"1.95"}
]}
4. RECURRING card transactions requests
4.1 RECURRING_SALE request
Recurring payments commonly used to create new transactions based on already stored cardholder information from previous operations.
RECURRING_SALE request has same logic as SALE request, the only difference is that you need to provide primary transaction id, and this request will create a secondary transaction with previously used cardholder data from primary transaction.
This request is sent by POST in the background (eg, through PHP CURL).
Request parameters
| Parameter | Description | Values | Required field |
|---|---|---|---|
| action | Recurring sale | RECURRING_SALE | + |
| async | Asynchronous or synchronous mode | Y or N (default N) | – |
| client_key | Unique client key (CLIENT_KEY) | + | |
| 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_description | Transaction description (product name) | String up to 1024 characters | + |
| recurring_first_trans_id | Transaction ID of the primary transaction in the Payment Platform | + | |
| recurring_token | Value obtained during the primary transaction | + | |
| 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) | + |
Response parameters
Response from Payment Platform is the same as by SALE command.
4.2 SCHEDULE request
Registers a schedule for the regular SALE secondary transactions. Transactions are created by Payment Platform, based on data taken from primary transaction.
This request is sent by POST in the background (eg, through PHP CURL).
Request parameters
| Parameter | Description | Values | Required field |
|---|---|---|---|
| action | Register recurring schedule | SCHEDULE | + |
| client_key | Unique client key (CLIENT_KEY) | + | |
| order_amount | The amount of the transaction | Numbers in the form XXXX.XX (without leading zeros) | + |
| order_description | Transaction description (product name) | String up to 1024 characters | + |
| recurring_first_trans_id | Transaction ID of the primary transaction in the Payment Platform | + | |
| period | Period in days to perform the payments | Numbers in the form XXX | + |
| init_period | Delay in days before performing the first payment. If not provided, the first payment will be done as soon as possible. |
Numbers in the form XXX | – |
| times | The number of times the payments will be done. Not provided or zero value means unlimited number of payments |
Numbers in the form XXX | – |
| hash | Special signature to validate your request to payment platform | ** (Appendix A) | + |
Response parameters
| Parameter | Description |
|---|---|
| action | SCHEDULE |
| result | SUCCESS |
| status | ENABLED |
| order_id | Transaction ID of the primary transaction in the Client system |
| trans_id | Transaction ID of the primary transaction in the Payment |
After processing each of scheduled RECURRING_SALE transactions, Payment Platform
sends response to Client’s Callback URL:
| Parameter | Description |
|---|---|
| action | RECURRING_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) |
| hash | Special signature, used to validate callback ** (Appendix A) |
4.3 DESCHEDULE request
This request disables previously set schedule.
This request is sent by POST in the background (eg, through PHP CURL).
Request parameters
| Parameter | Description | Values | Required field |
|---|---|---|---|
| action | Register recurring schedule | DESCHEDULE | + |
| client_key | Unique client key (CLIENT_KEY) | + | |
| recurring_first_trans_id | Transaction ID of the primary transaction in the Payment Platform | + | |
| recurring_token | Value obtained during the primary transaction | + | |
| hash | Special signature to validate your request to payment platform | **(Appendix A) | + |
Response parameters
| Parameter | Description |
|---|---|
| action | DESCHEDULE |
| result | SUCCESS |
| status | DISABLED |
| order_id | Transaction ID of the primary transaction in the Client system |
| trans_id | Transaction ID of the primary transaction in the Payment Platform |
5. Dispute transactions processing
CHARGEBACK, SECOND_PRESENTMENT, SECOND_CHARGEBACK transactions are used to dispute already settled payment. CHARGEBACK, SECOND_CHARGEBACK are initiated by issuer and SECOND_PRESENTMENT is initiated by acquirer.
ARBITRATION is the last step of dispute cycle when decision is made by international payment system and result of Arbitration may be either ARBITRATION_WON or ARBITRATION_LOST.
REVERSAL transactions are used to reverse back previously made CHARGEBACK, SECOND_PRESENTMENT, SECOND_CHARGEBACK or ARBITRATION transactions.
When processing these transactions, Payment Platform sends notification to Client’s Callback URL.
CHARGEBACK notification parameters
| Parameter | Description |
|---|---|
| action | CHARGEBACK |
| result | SUCCESS |
| status | CHARGEBACK |
| order_id | Transaction ID in the Client system |
| trans_id | Transaction ID in the Payment Platform |
| amount | The amount of the chargeback |
| chargeback_date | System date of the chargeback |
| bank_date | Bank date of the chargeback |
| reason_code | Reason code of the chargeback |
| hash | Special signature, used to validate callback **(Appendix A) |
SECOND_PRESENTMENT notification parameters
| Parameter | Description |
|---|---|
| action | SECOND_PRESENTMENT |
| result | SUCCESS |
| status | SECOND_PRESENTMENT |
| order_id | Transaction ID in the Client system |
| trans_id | Transaction ID in the Payment Platform |
| amount | The amount of the second presentment |
| chargeback_date | System date of the second presentment |
| bank_date | Bank date of the second presentment |
| reason_code | Reason code of the second presentment |
| hash | Special signature, used to validate callback **(Appendix A) |
SECOND_CHARGEBACK notification parameters
| Parameter | Description |
|---|---|
| action | SECOND_CHARGEBACK |
| result | SUCCESS |
| status | SECOND_CHARGEBACK |
| order_id | Transaction ID in the Client system |
| trans_id | Transaction ID in the Payment Platform |
| amount | The amount of the second chargeback |
| chargeback_date | System date of the second chargeback |
| bank_date | Bank date of the second chargeback |
| reason_code | Reason code of the second chargeback |
| hash | Special signature, used to validate callback **(Appendix A) |
REVERSAL notification parameters
| Parameter | Description |
|---|---|
| action | CHARGEBACK_REVERSAL / SECOND_PRESENTMENT_REVERSAL / SECOND_CHARGEBACK_REVERSAL / ARBITRATION_REVERSAL |
| result | SUCCESS |
| status | SETTLED / CHARGEBACK / SECOND_PRESENTMENT / ARBITRATION_REVERSAL |
| order_id | Transaction ID in the Client system |
| trans_id | Transaction ID in the Payment Platform |
| trans_id | Transaction ID in the Payment Platform |
| chargeback_date | System date of the reversal transaction |
| bank_date | Bank date of the reversal transaction |
| reason_code | Reason code of the reversal transaction |
| hash | Special signature, used to validate callback **(Appendix A) |
ARBITRATION notification parameters
| Parameter | Description |
|---|---|
| action | ARBITRATION / ARBITRATION_WON / ARBITRATION_LOST |
| result | SUCCESS |
| status | ARBITRATION / ARBITRATION_WON / ARBITRATION_LOST |
| order_id | Transaction ID in the Client system |
| trans_id | Transaction ID in the Payment Platform |
| trans_id | Transaction ID in the Payment Platform |
| chargeback_date | System date of the arbitration transaction |
| bank_date | Bank date of the arbitration transaction |
| reason_code | Reason code of the arbitration transaction |
| hash | Special signature, used to validate callback **(Appendix A) |
6. Errors
In case error you get synchronous response from Payment Platform:
| Parameter | Description |
|---|---|
| result | ERROR |
| error_message | Error message |
7. Testing
You can make test requests using data below. Please note, that all transactions will be processed using Test engine
| Card number | Card expiration date (MM/YYYY) | Result |
|---|---|---|
| 4111111111111111 | 01/2024 | Successful sale with successful |
| 4111111111111111 | 02/2024 | Unsuccessful sale/recurring payment |
| 4111111111111111 | 05/2024 | Successful sale after 3DS verification with a manual sending of the result (HTML form) |
| 4111111111111111 | 06/2024 | Unsuccessful sale after 3DS verification with a manual sending of the result (HTML form) |
Hash is signature rule used either to validate your requests to payment platform or to validate callback from payment platform to your system. It must be md5 encoded string calculated by rules below:
* hash is calculated by the formula:
md5(strtoupper(strrev(email).CLIENT_PASS.strrev(substr(card_number,0,6).substr(card_number,-4))))
if parameter card_token is specified hash is calculated by the formula:
md5(strtoupper(strrev(email).CLIENT_PASS.strrev(card_token)))
** hash is calculated by the formula:
md5(strtoupper(strrev(email).CLIENT_PASS.trans_id.strrev(substr(card_number,0,6).substr(card_number,-4))))
Appendix B
Sample data of the sale request:
| action | SALE |
| async | N |
| client_key | ZPR2ZH2J2U |
| order_id | ORDER-12345 |
| order_amount | 1.99 |
| order_currency | USD |
| order_description | Product |
| card_number | 4111111111111111 |
| card_exp_month | 01 |
| card_exp_year | 2024 |
| card_cvv2 | 000 |
| payer_first_name | John |
| payer_last_name | Doe |
| payer_address | Big street |
| payer_country | US |
| payer_state | CA |
| payer_city | City |
| payer_zip | 123456 |
| payer_email | doe@example.com |
| payer_phone | 199999999 |
| payer_ip | 123.123.123.123 |
| term_url_3ds¹ | https://client.site.com/return.php |
| recurring_init | Y |
| hash | 02cdb60b5c923e06c1b1d71da94b2a39 |
The hash above was calculated for CLIENT_PASS equal to qH0AHYFkgTURksztWZxUZUydwFOmiBHZ
Sample curl request:
curl -d "action=SALE&client_key=ZPR2ZH2J2U&order_id=ORDER-12345&order_amount=1.99&order_currency=USD&order_description=Product&card_number=4111111111111111&card_exp_month=01&card_exp_year=2024&card_cvv2=000&payer_first_name=John&payer_last_name=Doe&payer_address=BigStreet&payer_country=US&payer_state=CA&payer_city=City&payer_zip=123456&payer_email=doe@example.com&payer_phone=199999999&payer_ip=123.123.123.123&term_url_3ds=https://client.site.com/return.php&recurring_init=Y&hash=02cdb60b5c923e06c1b1d71da94b2a39" https://test.apiurl.com -k
Sample response (synchronous mode)
The response if the sale is successful:
{"action":"SALE","result":"SUCCESS","status":"SETTLED","trans_id":"03346-89217-70541","order_id":"ORDER-12345","descriptor":"test","trans_date":"2012-04-0316:02:01","recurring_token":"a1a6de416405ada72bb47a49176471dc"}
The response if the sale is unsuccessful:
{"action":"SALE","result":"DECLINED","status":"DECLINED","trans_id":"03346-89214-54141","order_id":"ORDER-12345","trans_date":"2012-04-0316:02:01","decline_reason":"Declined by processing"}
The response if the transaction supports 3D-Secure:
{"action":"SALE","result":"REDIRECT","status":"3DS","trans_id":"03346-89225-87891","order_id":"ORDER-12345","trans_date":"2012-04-0316:02:02","redirect_url":"https:\/\/server_3ds.com/3ds.php","redirect_params":{"PaReq":"bc5865698ae46de4eba4c51f0359a714","MD":"111111111111111111111","TermUrl":"https:\/\/term_url.com/3ds\/67c14e5?trans_id=03346-89225-87891&hash=8b98db60fb3c24c14a6d7075241da38b"},"redirect_method":"POST"}
In case error:
{"result":"ERROR","error_message":"Error description"}
Sample response (asynchronous mode)
{"action":"SALE","result":"ACCEPTED","trans_id":"03346-89211-86461","order_id":"ORDER-12345","trans_date":"2012-04-03 16:02:01"}
In case error:
{"result":"ERROR","error_message":"Error description"}
Sample recurring sale request:
curl -d "action=RECURRING_SALE&client_key=ZPR2ZH2J2U&order_id=ORDER-12345&order_amount=1.99&order_description=Product&recurring_first_trans_id=03346-89217-70541&recurring_token=a1a6de416405ada72bb47a49176471dc&hash=02cdb60b5c923e06c1b1d71da94b2a39" https://test.apiurl.com -k
Sample response
{"action":"RECURRING_SALE","result":"SUCCESS","status":"SETTLED","trans_id":"03346-89220-33511","order_id":"ORDER-12345","descriptor":"test","trans_date":"2012-04-03 16:02:02"}
Sample schedule request:
curl -d "action=SCHEDULE&client_key=ZPR2ZH2J2U&order_id=ORDER-12345&order_amount=1.99&order_description=Product&recurring_first_trans_id=03346-89217-70541&recurring_token=a1a6de416405ada72bb47a49176471dc&period=30&init_period=5×=10&hash=02cdb60b5c923e06c1b1d71da94b2a39"https://test.apiurl.com -k
Sample response
{"action":"SCHEDULE","result":"SUCCESS","status":"ENABLED","trans_id":"03346-89220-33511","order_id":"ORDER-12345"}
Sample deschedule request:
curl-d "action=DESCHEDULE&client_key=ZPR2ZH2J2U&recurring_first_trans_id=03346-89217-70541 &recurring_token=a1a6de416405ada72bb47a49176471dc&hash=02cdb60b5c923e06c1b1d71da94b2a39" https://test.apiurl.com -k
Sample response
{"action":"DESCHEDULE","result":"SUCCESS","status":"DISABLED","trans_id":"03346-89220-33511","order_id":"ORDER-12345"}
Sample creditvoid request:
curl -d "action=CREDITVOID&client_key=ZPR2ZH2J2U&trans_id=03346-89211-86461&amount=10.00&hash=6b957fca41c353ac344fcad47f0cbf97" https://test.apiurl.com -k
Sample response
{"action":"CREDITVOID","result":"ACCEPTED","trans_id":"03346-89211-86461","order_id":"ORDER-12345"}
While you can’t afford to pay too much for the custom writing of your essay If you’re interested, then you may be wondering of where you can get a low cost essay writing company. You can expect a high-quality service for a fair price. But make sure you are conscious of the things you should look for. You can choose between reputable as well as cheap options. The first will provide an inexpensive paper composed by experts at the cost of a fair price.