API (Documentation)
support

1. Introduction

This document describes integration procedures and POST protocol usage for ecommerce merchants.

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.

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.

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 PaymentPlatform URL (PAYMENT_URL). In response Payment Platform will return the JSON (http://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:

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.

2.4 List of possible transaction results and statuses

Result – value that system returns on request. Possible results are:

Status – actual status of transaction in Payment Platform. Possible statuses are:

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

¹ – This field becomes optional if card_token is specified
² – 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:

Unsuccessful sale response:

3D-Secure transaction response:

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.

Callback parameters

Successful sale response:

Unsuccessful sale response:

3D-Secure transaction response:

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

Response parameters

Successful capture response:

Unsuccessful capture response:

Callback parameters

Successful capture response:

Unsuccessful capture response:

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

Response parameters

Callback parameters

Successful refund/reversal response

Unsuccessful refund/reversal response

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

Response parameters

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

Response parameters

² –  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

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

Response parameters

After processing each of scheduled RECURRING_SALE transactions, Payment Platform sends response to Client’s Callback URL:

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

Response parameters

5. Dispute transactions processing

5.1 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

SECOND_PRESENTMENT notification parameters

SECOND_CHARGEBACK notification parameters

REVERSAL notification parameters

ARBITRATION notification parameters

6. Errors

6.1 Errors

In case error you get synchronous response from Payment Platform:

7. Testing

7.1 Testing

You can make test requests using data below. Please note, that all transactions will be processed using Test engine.

8. Appendix

8.1 Appendix A

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))))

8.2 Appendix B

 Sample data of the sale request:

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=2020&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_em [email protected]&payer_phone=199999999&payer_ip=123.123.123.123&term_url_3ds= http://client.site.com/return.php&recurring_init=Y&hash=02cdb60b5c923e06c1b1d71d a94b2a39"	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-03 16: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-03 16: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-03 16: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":"033 46-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&times=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"}