S2S CARD

Version: 3.4.1
Released: 2022/10/13

Introduction#

This document describes integration procedures and POST protocol usage for e-commerce merchants.

S2S CARD protocol implements acquiring payments (purchases) with specific API interaction using.

Integration process#

Merchant registration#

Before you get an account to access Payment Platform, you must provide the following data to the Payment Platform administrator.

Data	Description
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. It is mandatory if your account supports 3D-Secure. The length of Notification URL should not be more than 255 symbols.
Contact email	Email address of Responsible Person who will monitor transactions, conduct refunds, etc.

With all Payment Platform POST requests at Notification URL the Merchant must return the string OK if he/she successfully received data or return ERROR.

You should get the following information from administrator to begin working with the Payment Platform.

Data	Description
CLIENT_KEY	Unique key to identify the account in Payment Platform (used as request parameter). In the administration platform this parametercorresponds to the Merchant key field
PASSWORD	Password for Client authentication in Payment Platform (used for calculating hash parameter). In the administration platform this parameter corresponds to the Password field
PAYMENT_URL	URL to request the Payment Platform

Interaction with Payment Platform#

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 (http://json.org/) encoded string.

3DS features#

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 cardholder 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.

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 Notification URL action.

Redirect parameters#

For 3DS-payments, the response for SALE request may contain an object with the redirect parameters. The redirect parameters are provided in the "key-value" format.

To get the parameters in that format, you need to use an endpoint https://{PAYMENT_URL}/post.

Response with key-value format

    "redirect_params": {        "Param1": "Value1",        "Param2": "Value2"    }

As well you can receive redirect parameters as an array with objects that contain the name and value parameters.

To get the parameters in that format, you need to use an endpoint https://{PAYMENT_URL}/v2/post.

Response with "name" and "value" parameters

    "redirect_params": [        {            "name": "Param1",            "value": "Value1"        },        {            "name": "Param2",            "value": "Value2"        }    ]

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
CREDIT2CARD	Creates CREDIT2CARD transaction
GET_TRANS_STATUS	Gets status of transaction in Payment Platform
GET_TRANS_DETAILS	Gets details of the order from Payment platform
GET_TRANS_STATUS_BY_ORDER	Gets the status of the most recent transaction in the order's transaction subsequence from Payment platform
RECURRING_SALE	Creates SALE or AUTH transaction using previously used cardholder data

Recurring schedule operations#

Action	Description
CREATE_SCHEDULE	Creates a new schedule object
PAUSE_SCHEDULE	Suspends the scheduled payments associated with schedule. A schedule can only be paused if its parameter "paused" has a value "N". Paused schedule can't be used for the new recurring payments until it is released via RUN_SCHEDULE
RUN_SCHEDULE	Releases the schedule which was paused via PAUSE_SCHEDULE. It re-schedules cycle of payments and set the value "N" for "paused" parameter for schedule
DELETE_SCHEDULE	Deleting schedule means that it can’t be used in the recurring payments
SCHEDULE_INFO	Retrieves the details of an existing schedule. You only need to supply the unique schedule identifier that was returned upon schedule creation
DESCHEDULE	Stops the payments by the schedule

Following actions cannot be made by request, they are initiated 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

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
REDIRECT	The transaction is redirected
PENDING	The transaction awaits CAPTURE
PREPARE	Status is undetermined, final status will be sent in callback
SETTLED	Successful transaction
REVERSAL	Transaction for which reversal was made
REFUND	Transaction for which refund was made
CHARGEBACK	Transaction for which chargeback was made
DECLINED	Not successful transaction

PAYMENT OPERATIONS#

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 (e.g. through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	Sale	SALE	+
`client_key`	Unique key (client_key)	UUID format value	+
`channel_id`	Payment channel (Sub-account)	String up to 16 characters	-
`order_id`	Transaction ID in the Merchants system	String up to 255 characters	+
`order_amount`	The amount of the transaction	Numbers in the format XXXX.XX Pay attention that amount format depends on currency exponent. If exponent = 0, then amount is integer (without decimals). It used for currencies: CLP, VND, ISK, UGX, KRW, JPY. If exponent = 3, then format: XXXX.XXX (with 3 decimals). It used for currencies: BHD, JOD, KWD, OMR, TND.	+
`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_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 10 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	+
`term_url_target`	Name of, or keyword for a browsing context where Customer should be returned according to HTML specification.	String up to 1024 characters Possible values: `_blank`, `_self`, `_parent`, `_top` or custom iframe name (default `_top`). Find the result of applying the values in the HTML standard description (Browsing context names)	-
`recurring_init`	Initialization of the transaction with possible following recurring	Y or N (default N)	-
`schedule_id`	Schedule ID for recurring payments	String	-
`auth`	Indicates that transaction must be only authenticated, but not captured	Y or N (default N)	-
`parameters`	Object that contains extra-parameters required by the acquirer	Format: `"parameters": {"param1" : "value1", "param2" : "value2", "param3" : "value3"}` See Appendix C for more details	-
`hash`	Special signature to validate your request to Payment Platform	See Appendix A, Formula 1	+

*This field becomes optional if card_token is specified

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 Notification URL.

Synchronous mode#

Successful sale response#

Parameter	Description
`action`	SALE
`result`	SUCCESS
`status`	PENDING / PREPARE / SETTLED; only PENDING when `auth` = Y
`order_id`	Transaction ID in the Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Descriptor from the bank, the same as cardholder will see in the bank statement
`recurring_token`	Recurring token (get if account support recurring sales and was initialization transaction for following recurring)
`schedule_id`	Schedule ID for recurring payments. It is available if schedule is used for recurring sale
`card_token`	If the parameter `req_token` was enabled Payment Platform returns the token value
`amount`	Order amount
`currency`	Currency

Unsuccessful sale response#

Parameter	Description
`action`	SALE
`result`	DECLINED
`status`	DECLINED
`order_id`	Transaction ID in the Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Descriptor from the bank, the same as cardholder will see in the bank statement
`amount`	Order amount
`currency`	Currency
`decline_reason`	The reason why the transaction was declined

3D-Secure transaction response#

Parameter	Description
`action`	SALE
`result`	REDIRECT
`status`	3DS / REDIRECT
`order_id`	Transaction ID in the Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Descriptor from the bank, the same as cardholder will see in the bank statement
`amount`	Order amount
`currency`	Currency
`redirect_url`	URL to which the Merchant should redirect the Customer
`redirect_params`	Object of specific 3DS parameters. It is array if `redirect_params` have no data. The availability of the `redirect_params` depends on the data transmitted by the acquirer. `redirect_params` may be missing. It usually happens when `redirect_method` = GET
`redirect_method`	The method of transferring parameters (POST / GET)

Callback parameters#

Successful sale response#

Parameter	Description
`action`	SALE
`result`	SUCCESS
`status`	PENDING/PREPARE/SETTLED
`order_id`	Transaction ID in the Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`hash`	Special signature, used to validate callback, see Appendix A, Formula 2
`recurring_token`	Recurring token (get if account support recurring sales and was initialization transaction for following recurring)
`schedule_id`	It is available if schedule is used for recurring sale
`card_token`	If the parameter `req_token` was enabled Payment Platform returns the token value
`card`	Card mask
`card_expiration_date`	Card expiration date
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Descriptor from the bank, the same as cardholder will see in the bank statement
`amount`	Order amount
`currency`	Currency

Unsuccessful sale response#

Parameter	Description
`action`	SALE
`result`	DECLINED
`status`	DECLINED
`order_id`	Transaction ID in the Merchant'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, see Appendix A, Formula 2

3D-Secure transaction response#

Parameter	Description
`action`	SALE
`result`	REDIRECT
`status`	3DS/REDIRECT
`order_id`	Transaction ID in the Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`hash`	Special signature, used to validate callback, see Appendix A, Formula 2
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Descriptor from the bank, the same as cardholder will see in the bank statement
`amount`	Order amount
`currency`	Currency
`redirect_url`	URL to which the Merchant should redirect the Customer
`redirect_params`	Object with the parameters. It is array if `redirect_params` have no data. The availability of the `redirect_params` depends on the data transmitted by the acquirer. `redirect_params` may be missing. It usually happens when `redirect_method` = GET
`redirect_method`	The method of transferring parameters (POST/GET)

CAPTURE request#

CAPTURE request is used to submit previously authorized transaction (created by SALE request with parameter auth = Y). Hold funds will be transferred to Merchants account.

This request is sent by POST in the background (e.g. through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	Capture previously authenticated transaction	CAPTURE	+
`client_key`	Unique key (client_key)	UUID format value	+
`trans_id`	Transaction ID in the Payment Platform	UUID format value	+
`amount`	The amount for capture. Only one partial capture is allowed	Numbers in the format XXXX.XX Pay attention that amount format depends on currency exponent. If exponent = 0, then amount is integer (without decimals). It used for currencies: CLP, VND, ISK, UGX, KRW, JPY. If exponent = 3, then format: XXXX.XXX (with 3 decimals). It used for currencies: BHD, JOD, KWD, OMR, TND.	-
`hash`	Special signature to validate your request to payment platform	see Appendix A, Formula 2	+

Response parameters#

Synchronous mode#

Successful capture response#

Parameter	Description
`action`	CAPTURE
`result`	SUCCESS
`status`	SETTLED
`amount`	Amount of capture
`order_id`	Transaction ID in the Merchants system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Descriptor from the bank, the same as cardholder will see in the bank statement
`currency`	Currency

Unsuccessful capture response#

Parameter	Description
`action`	CAPTURE
`result`	DECLINED
`status`	PENDING
`order_id`	Transaction ID in the Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Descriptor from the bank, the same as cardholder will see in the bank statement
`amount`	Amount of capture
`currency`	Currency
`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 Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`amount`	Amount of capture
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Descriptor from the bank, the same as cardholder will see in the bank statement
`currency`	Currency
`hash`	Special signature, used to validate callback, see Appendix A, Formula 2

Unsuccessful capture response#

Parameter	Description
`action`	CAPTURE
`result`	DECLINED
`status`	PENDING
`order_id`	Transaction ID in the Merchant'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, see Appendix A, Formula 2

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 (e.g. through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	CREDITVOID	CREDITVOID	+
`client_key`	Unique key (client_key)	UUID format value	+
`trans_id`	Transaction ID in the Payment Platform	UUID format value	+
`amount`	The amount of full or partial refund. If amount is not specified, full refund will be issued. In case of partial refund this parameter is required. Several partial refunds are allowed	Numbers in the format XXXX.XX Pay attention that amount format depends on currency exponent. If exponent = 0, then amount is integer (without decimals). It used for currencies: CLP, VND, ISK, UGX, KRW, JPY. If exponent = 3, then format: XXXX.XXX (with 3 decimals). It used for currencies: BHD, JOD, KWD, OMR, TND.	-
`hash`	Special signature to validate your request to Payment Platform	see Appendix A, Formula 2	+

Response parameters#

Synchronous mode#

Parameter	Description
`action`	CREDITVOID
`result`	ACCEPTED
`order_id`	Transaction ID in the Merchant'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 - for full refund SETTLED - for partial refund
`order_id`	Transaction ID in the Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`creditvoid_date`	Date of the refund/reversal
`amount`	Amount of refund
`hash`	Special signature, used to validate callback, see Appendix A, Formula 2

Unsuccessful refund/reversal response#

Parameter	Description
`action`	CREDITVOID
`result`	DECLINED
`order_id`	Transaction ID in the Merchant's 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, see Appendix A, Formula 2

CREDIT2CARD request#

CREDIT2CARD protocol implements money transfers transactions between merchant's account and credit card (Card Credit or Account-to-Card payment) with using specific API.

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 (e.g., through PHP CURL).

Request Parameters#

Parameter	Description	Values	Required
`action`	Action type	CREDIT2CARD	+
`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	+
`card_number`	Credit Card Number		+
`hash`	Special signature to validate your request to Payment Platform	see Appendix A, Formula 5	+

Example Request

curl –d "action=CREDIT2CARD&client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004& channel_id=test&order_id=123456789&order_amount=1.03&order_currency=USD& order_description=wine&card_number=4917111111111111& hash=a1a6de416405ada72bb47a49176471dc"[https://test.apiurl.com](https://test.apiurl.com/) -k

Response Parameters#

You will get JSON encoded string with transaction result.

Successful response

Parameter	Description
`action`	CREDIT2CARD
`result`	SUCCESS
`status`	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.

Response Example (Successful result)

{ "action": "CREDIT2CARD", "result": "SUCCESS", "status": "SETTLED", "order_id": "1613117050", "trans_id": "e5098d62-6d08-11eb-9da3-0242ac120013", "trans_date": "2021-02-12 08:04:15" }

Unsuccessful response

Parameter	Description
`action`	CREDIT2CARD
`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

Response Example (Unsuccessful result)

{ "action": "CREDIT2CARD", "result": "DECLINED", "status": "DECLINED", "order_id": "1613117050", "trans_id": "e5098d62-6d08-11eb-9da3-0242ac120013", "trans_date": "2021-02-12 08:04:15", "decline_reason": "Declined by processing" }

Callback parameters#

Successful response

Parameter	Description
`action`	CREDIT2CARD
`result`	SUCCESS
`status`	SETTLED
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Date of CREDIT2CARD action
`hash`	Special signature to validate callback. See Appendix A, Formula 6

Callback Example (Successful result)

"action=CREDIT2CARD&result=SUCCESS&status=SETTLED&order_id=123456789&trans_id=1d152122-6c86-11eb-8a49-0242ac120013&hash=84dc0713fa38f18edb85da7aa94eca2e&trans_date=2021-02-11+16%3A28%3A04"

Unsuccessful 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`	Date of CREDIT2CARD action
`decline_reason`	Reason of transaction decline.It shows for the transactions with the "DECLINED" status
`hash`	Special signature to validate callback. See Appendix A, Formula 6

Callback Example (Unsuccessful result)

"action=CREDIT2CARD&result=SUCCESS&status=SETTLED&order_id=123456789&trans_id=1d152122-6c86-11eb-8a49-0242ac120013&hash=84dc0713fa38f18edb85da7aa94eca2e&trans_date=2021-02-11+16%3A28%3A04"

GET_TRANS_STATUS request#

Gets order status from Payment Platform. This request is sent by POST in the background (e.g. through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	GET_TRANS_STATUS	GET_TRANS_STATUS	+
`client_key`	Unique key (client_key)	UUID format value	+
`trans_id`	Transaction ID in the Payment Platform	UUID format value	+
`hash`	Special signature to validate your request to Payment Platform	CREDIT2CARD - see Appendix A, Formula 6 Others - see Appendix A, Formula 2	+

Response parameters#

Parameter	Description
`action`	GET_TRANS_STATUS
`result`	SUCCESS
`status`	3DS / REDIRECT / PENDING / PREPARE / DECLINED / SETTLED / REVERSAL / REFUND / CHARGEBACK
`order_id`	Transaction ID in the Merchant`s system
`trans_id`	Transaction ID in the Payment Platform
`decline_reason`	Reason of transaction decline. It shows for the transactions with the DECLINED status
`recurring_token`	Token for recurring. It shows when the next conditions are met for the SALE transaction: - transaction is successful - SALE request contained `recurring_init` parameter with the value 'Y'

GET_TRANS_DETAILS request#

Gets all history of transactions by the order. This request is sent by POST in the background (e.g. through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	GET_TRANS_DETAILS	GET_TRANS_DETAILS	+
`client_key`	Unique key (client_key)	UUID format value	+
`trans_id`	Transaction ID in the Payment Platform	UUID format value	+
`hash`	Special signature to validate your request to Payment Platform	CREDIT2CARD - see Appendix A, Formula 6 Others - see Appendix A, Formula 2	+

Response parameters#

Parameter	Description
`action`	GET_TRANS_DETAILS
`result`	SUCCESS
`status`	3DS / REDIRECT / PENDING / PREPARE / DECLINED / SETTLED / REVERSAL / REFUND / CHARGEBACK
`order_id`	Transaction ID in the Merchant`s system
`trans_id`	Transaction ID in the Payment Platform
`name`	Payer name
`mail`	Payer mail
`ip`	Payer IP
`amount`	Order amount
`currency`	Currency
`card`	Card in the format XXXXXX****XXXX
`decline_reason`	Reason of transaction decline.It shows for the transactions with the DECLINED status
`recurring_token`	Token for recurring. It shows when the next conditions are met for the SALE transaction: - transaction is successful - SALE request contained `recurring_init` parameter with the value 'Y' - SALE request contained card data which was used for the first time
`schedule_id`	Schedule ID for recurring payments
`transactions`	Array of transactions with the parameters: - date - type (sale, 3ds, auth, capture, credit, chargeback, reversal, refund) - status (success, waiting, fail) - amount

Response Example

{    "action": "GET_TRANS_DETAILS",    "result": "SUCCESS",    "status": "REFUND",    "order_id": "1646655381neural",    "trans_id": "66624eba-9e10-11ec-aa41-0242ac130002",    "name": "John Rikher",    "mail": "test@gmail.com",    "ip": "192.169.217.106",    "amount": "0.02",    "currency": "USD",    "card": "522864******0691",    "transactions": [        {            "type": "3DS",            "status": "success",            "date": "2022-03-07 12:16:23",            "amount": "0.02"        },        {            "type": "SALE",            "status": "success",            "date": "2022-03-07 12:16:31",            "amount": "0.02"        },        {            "type": "REFUND",            "status": "success",            "date": "2022-03-07 12:20:14",            "amount": "0.02"        }    ]}

GET_TRANS_STATUS_BY_ORDER request#

Gets the status of the most recent transaction in the order's transaction subsequence from Payment Platform. This request is sent by POST in the background (e.g. through PHP CURL).

It is recommended to pass an unique order_id in the payment request. That way, it will be easier to uniquely identify the payment by order_id. This is especially important if cascading is configured. In this case, several intermediate transactions could be created within one payment.

Request parameters#

Parameter	Description	Values	Required field
`action`	GET_TRANS_STATUS_BY_ORDER	GET_TRANS_STATUS_BY_ORDER	+
`client_key`	Unique key (client_key)	UUID format value	+
`order_id`	Transaction ID in the Merchants system	UUID format value	+
`hash`	Special signature to validate your request to Payment Platform	see Appendix A, Formula 7	+

Response parameters#

Parameter	Description
`action`	GET_TRANS_STATUS_BY_ORDER
`result`	SUCCESS
`status`	3DS / REDIRECT / PENDING / PREPARE / DECLINED / SETTLED / REVERSAL / REFUND / CHARGEBACK
`order_id`	Transaction ID in the Merchant`s system
`trans_id`	Transaction ID in the Payment Platform
`decline_reason`	Reason of transaction decline. It shows for the transactions with the DECLINED status
`recurring_token`	Token for recurring. It shows when the next conditions are met for the SALE transaction: - transaction is successful - SALE request contained `recurring_init` parameter with the value 'Y'

RECURRING_SALE request#

Recurring payments are 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 (e.g. through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	Recurring sale	RECURRING_SALE	+
`client_key`	Unique key (CLIENT_KEY)	UUID format value	+
`order_id`	Transaction ID in the Merchant's system	String up to 255 characters	+
`order_amount`	The amount of the transaction	Numbers in the format XXXX.XX Pay attention that amount format depends on currency exponent. If exponent = 0, then amount is integer (without decimals). It used for currencies: CLP, VND, ISK, UGX, KRW, JPY. If exponent = 3, then format: XXXX.XXX (with 3 decimals). It used for currencies: BHD, JOD, KWD, OMR, TND.	+
`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	UUID format value	+
`recurring_token`	Value obtained during the primary transaction	UUID format value	+
`schedule_id`	Schedule ID for recurring payments	String	-
`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	see Appendix A, Formula 1	+

Response parameters#

Response from Payment Platform is the same as by SALE command, except for the value of the difference parameter
action = RECURRING_SALE. You will receive a JSON encoded string with the result of the transaction.

CHARGEBACK notification parameters#

CHARGEBACK transactions are used to dispute already settled payment.

When processing these transactions Payment Platform sends notification to Merchant`s Notification URL.

Parameter	Description
`action`	CHARGEBACK
`result`	SUCCESS
`status`	CHARGEBACK
`order_id`	Transaction ID in the Merchant`s 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 to validate callback, see Appendix A, Formula 2

RECURRING SCHEDULE OPERATIONS#

Protocol implements schedules for recurring payments with specific API interaction using. Schedules allow you to charge a customer on a recurring basis.

To work with the schedules you must send the server to server HTTPS request to Payment Platform URL (PAYMENT_URL) with the fields listed in "Recurring schedule actions" section. In the response Payment Platform will return the JSON (http://json.org/) encoded string.

CREATE_SCHEDULE request#

To create a new schedule you need to send the request with the parameters listed below. This request is sent by POST in the background (e.g., through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	Action to create a new schedule - fixed value	CREATE_SCHEDULE	+
`client_key`	Unique key (CLIENT_KEY)	UUID format value	+
`name`	Name of schedule	String up to 100 characters	+
`interval_length`	Interval length - how often the payments occurs. Cannot be set "0". For example, to set a schedule for payments every 15 days, you need to set: `interval_length` = 15, `interval_unit` = day	Number	+
`interval_unit`	Interval unit	Possible values are "day" and "month"	+
`day_of_month`	Day of month when payment has to occur. Available only if interval_unit = month. Possible values: from 1 to 31. If day_of_month = 29, 30, or 31 and there are no days 29, 30, or 31 in the month, then the last day of the month is used. If day_of_month is not defined, then payment occurs on the day the initiating payment is created	Number from 1 to 31	-
`payments_count`	Payments count in schedule	Number	+
`delays`	Number of skipped intervals of the scheduled before payment cycle starts	Number	-
`hash`	Special signature to validate your request to Payment Platform	see Appendix A, Formula 3	+

Response parameters#

You will get JSON encoded string with the request result

Parameter	Description
`action`	CREATE_SCHEDULE
`result`	SUCCESS
`schedule_id`	Schedule ID in the Payment Platform

PAUSE_SCHEDULE request#

Suspends the schedule and assigns value "Y" for "paused" parameter. This request is sent by POST in the background (e.g., through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	Action to pause a schedule - fixed value.	PAUSE_SCHEDULE	+
`client_key`	Unique key (CLIENT_KEY)	UUID format value	+
`schedule_id`	Schedule ID in the Payment Platform	UUID format value	+
`hash`	Special signature to validate your request to Payment Platform	see Appendix A, Formula 4	+

Response parameters#

Parameter	Description
`action`	PAUSE_SCHEDULE
`result`	SUCCESS

RUN_SCHEDULE request#

Releases the paused schedule and assigns value "N" for "paused" parameter. This request is sent by POST in the background (e.g., through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	Action to run a schedule - fixed value	RUN_SCHEDULE	+
`client_key`	Unique key (CLIENT_KEY)	UUID format value	+
`schedule_id`	Schedule ID in the Payment Platform	UUID format value	+
`hash`	Special signature to validate your request to Payment Platform	see Appendix A, Formula 4	+

Response parameters#

Parameter	Description
`action`	RUN_SCHEDULE
`result`	SUCCESS

DELETE_SCHEDULE request#

To delete an existing schedule you need to send the request with the parameters listed below. This request is sent by POST in the background (e.g., through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	Action to delete a schedule - fixed value	DELETE_SCHEDULE	+
`client_key`	Unique key (CLIENT_KEY)	UUID format value	+
`schedule_id`	Schedule ID in the Payment Platform	UUID format value	+
`hash`	Special signature to validate your request to Payment Platform	see Appendix A, Formula 4	+

Response parameters#

Parameter	Description
`action`	DELETE_SCHEDULE
`result`	SUCCESS

SCHEDULE_INFO request#

Gets information about an existing schedule. This request is sent by GET in the background (e.g., through PHP CURL).

Request parameters#

Parameter	Description	Values	Required field
`action`	Action to get a schedule info - fixed value	SCHEDULE_INFO	+
`client_key`	Unique key (CLIENT_KEY)	UUID format value	+
`schedule_id`	Schedule ID in the Payment Platform	UUID format value	+
`hash`	Special signature to validate your request to Payment Platform	see Appendix A, Formula 4	+

Response parameters#

Parameter	Description
`action`	SCHEDULE_INFO
`name`	Name of schedule
`interval_length`	Interval length - how often the payments occurs
`interval_unit`	Interval unit
`day_of_month`	Day of month when payment has to occur. Available only if interval_unit = month
`payments_count`	Payments count in schedule
`delays`	Number of skipped intervals of the scheduled before payment cycle starts
`paused`	Shows if schedule is in pause (Y or N)

DESCHEDULE request#

To deschedule recurring and stop the payments by the schedule.

Parameter	Description	Values	Required field
`action`	Action to perform	DESCHEDULE	+
`client_key`	Unique key (CLIENT_KEY)	UUID format value	+
`recurring_token`	Value obtained during the primary transaction	UUID format value	+
`schedule_id`	Schedule ID in the Payment Platform	UUID format value	+
`hash`	Special signature to validate your request to Payment Platform	see Appendix A, Formula 4	+

Errors#

In case of an error you get synchronous response from Payment Platform:

Parameter	Description
`result`	ERROR
`error_message`	Error message
`error_code`	Error code

The list of the error codes is shown below.

Code	Description
204002	Enabled merchant mappings or MIDs not found.
204003	Payment type not supported.
204004	Payment method not supported.
204005	Payment action not supported.
204006	Payment system/brand not supported.
204007	Day MID limit is not set or exceeded.
204008	Day Merchant mapping limit is not set or exceeded.
204009	Payment type not found.
204010	Payment method not found.
204011	Payment system/brand not found.
204012	Payment currency not found.
204013	Payment action not found.
204014	Month MID limit is exceeded.
204015	Week Merchant mapping limit is exceeded.
208001	Payment not found.
208002	Not acceptable to request the 3ds for payment not in 3ds status.
208003	Not acceptable to request the capture for payment not in pending status.
208004	Not acceptable to request the capture for amount bigger than auth amount.
208005	Not acceptable to request the refund for payment not in settled or pending status.
208006	Not acceptable to request the refund for amount bigger than payment amount.
208008	Not acceptable to request the reversal for amount bigger than payment amount.
208009	Not acceptable to request the reversal for partial amount.
208010	Not acceptable to request the chargeback for amount bigger than payment's amount.
205005	Card token is invalid or not found.
205006	Card token is expired.
205007	Card token is not accessible.
400	Duplicate request.
400	Previous payment not completed.

Sample of error-response

{"result": "ERROR",    "error_code": 100000,    "error_message": "Request data is invalid.",    "errors": [        {            "error_code": 100000,            "error_message": "card_number: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "card_exp_month: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "card_exp_year: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "card_cvv2: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "order_id: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "order_amount: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "order_amount: This value should be greater than 0."        },        {            "error_code": 100000,            "error_message": "order_currency: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "order_description: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "payer_first_name: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "payer_last_name: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "payer_address: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "payer_country: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "payer_city: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "payer_zip: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "payer_email: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "payer_phone: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "payer_ip: This value should not be blank."        },        {            "error_code": 100000,            "error_message": "term_url_3ds: This value should not be blank."        }    ]}

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)	Testing / Result
4111111111111111	01/2025	This card number and card expiration date must be used for testing successful sale Response on successful SALE request: `{action: SALE, result: SUCCESS, status: SETTLED}` Response on successful AUTH request: `{action: SALE, result: SUCCESS, status: PENDING}`
4111111111111111	02/2025	This card number and card expiration date must be used for testing unsuccessful sale Response on unsuccessful SALE request: `{action: SALE, result: DECLINED, status: DECLINED}` Response on unsuccessful AUTH request: `{action: SALE, result: DECLINED, status: DECLINED}`
4111111111111111	03/2025	This card number and card expiration date must be used for testing unsuccessful CAPTURE after successful AUTH Response on successful AUTH request: `{action: SALE, result: SUCCESS, status: PENDING}` Response on unsuccessful CAPTURE request: `{action: CAPTURE, result: DECLINED, status: PENDING}`
4111111111111111	05/2025	This card number and card expiration date must be used for testing successful sale after 3DS verification Response on VERIFY request: `{action: SALE, result: REDIRECT, status: 3DS}` After return from ACS: `{action: SALE, result: SUCCESS, status: SETTLED}`
4111111111111111	06/2025	This card number and card expiration date must be used for testing unsuccessful sale after 3DS verification Response on VERIFY request: `{action: SALE, result: REDIRECT, status: 3DS}` After return from ACS: `{action: SALE, result: DECLINED, status: DECLINED}`
4111111111111111	12/2025	This card number and card expiration date must be used for testing successful sale after redirect Response on SALE/AUTH request: `{action: SALE, result: REDIRECT, status: REDIRECT}` Return to the system: `{action: SALE, result: SUCCESS, status: SETTLED}`
4111111111111111	12/2026	This card number and card expiration date must be used for testing unsuccessful sale after redirect Response on SALE/AUTH request: `{action: SALE, result: REDIRECT, status: REDIRECT}` Return to the system: `{action: SALE, result: DECLINED, status: DECLINED}`

Appendix A (Hash)#

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:

Formula 1:

hash is calculated by the formula:

md5(strtoupper(strrev(email).PASSWORD.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).PASSWORD.strrev(card_token)))

Formula 2:

hash is calculated by the formula:

md5(strtoupper(strrev(email).PASSWORD.trans_id.strrev(substr(card_number,0,6).substr(card_number,-4))))

Formula 3:

hash for Create a schedule is calculated by the formula:

md5(strtoupper(strrev(PASSWORD)));

Formula 4:

hash for Other schedules is calculated by the formula:

md5(strtoupper(strrev(schedule_id + PASSWORD)));

Formula 5:

hash for CREDIT2CARD request is calculated by the formula:

md5(strtoupper(PASSWORD.strrev(substr(card_number,0,6).substr(card_number,-4))))

if card_token is specified hash is calculated by the formula:

md5(strtoupper(PASSWORD. strrev(card_token)))

Formula 6:

hash is calculated by the formula:

md5(strtoupper(PASSWORD.trans_id.strrev(substr(card_number,0,6).substr(card_number,-4))))

Formula 7:

hash is calculated by the formula:

md5(strtoupper(strrev(email).PASSWORD.order_id.strrev(substr(card_number,0,6).substr(card_number,-4))))

Appendix B (Examples)#

Please review carefully the list of parameters before using the examples. Some parameters may be missing in the examples.

Requests examples are for reference only. If you will use them unchanged you will receive an error in the response.

You have to set your own values for parameters (client_key and hash in particular).

SALE request sample#

Sample data of the sale request#

Parameter	Valid value
`action`	SALE
`client_key`	c2b8fb04-110f-11ea-bcd3-0242c0a85004
`order_id`	ORDER-12345
`order_amount`	1.99
`order_currency`	USD
`order_description`	Product
`card_number`	4111111111111111
`card_exp_month`	01
`card_exp_year`	2025
`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 1`	http://client.site.com/return.php
`hash`	2702ae0c4f99506dc29b5615ba9ee3c0

The hash above was calculated for PASSWORD equal to13a4822c5907ed235f3a068c76184fc3.

Sample curl request

curl –d "action=SALE&client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004&order_id=ORDER12345&order_amount=1.99&order_currency=USD&order_description=Product&card_number=4111111111111111&card_exp_month=01&card_exp_year=2025&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=http://client.site.com/return.php&parameters[param1]=value1&parameters[param2]=value2&parameters[param3]=value3&hash=2702ae0c4f99506dc29b5615ba9ee3c0" https://test.apiurl.com -k

Sample response (synchronous mode)#

The response if the sale is successful

{"action":"SALE","result":"SUCCESS","status":"SETTLED","order_id":"ORDER-12345","trans_id":"aaaff66a-904f-11ea-833e-0242ac1f0007","trans_date":"2012-04-03 16:02:01","descriptor":"test","amount":"0.02","currency":"USD"}

The response if the sale is unsuccessful

{"action":"SALE","result":"DECLINED","status":"DECLINED","order_id":"ORDER-12345","trans_id":"aaaff66a-904f-11ea-833e-0242ac1f0007","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","order_id":"1588856266Intelligent","trans_id":"595ceeea-9062-11ea-aa1b-0242ac1f0007","trans_date":"2012-04-03 16:02:01","descriptor":"Descriptor","amount":"0.02","currency":"USD","redirect_url":"https://some.acs.endpoint.com","redirect_params":    {    "PaReq":"M0RTIE1hc3RlciBVU0QgU1VDQ0VTUw==",    "MD":"595ceeea-9062-11ea-aa1b-0242ac1f0007",    "TermUrl":"https://192.168.0.1:8101/verify/3ds/595ceeea-9062-11ea-aa1b-0242ac1f0007/7d6b9b240ff2779b7209aef786f808d1"    },"redirect_method":"POST"}

In case of redirect_params is empty

{"action":"SALE","result":"REDIRECT","status":"3DS","order_id":"1588856266Intelligent","trans_id":"595ceeea-9062-11ea-aa1b-0242ac1f0007","trans_date":"2012-04-03 16:02:01","descriptor":"Descriptor","amount":"0.02","currency":"USD","redirect_url":"https://some.acs.endpoint.com","redirect_params":[],"redirect_method":"POST"}

In case of an error (sample is shown in the “Errors” section)

{"result":"ERROR","error_message":"Error description"}

Sample response (asynchronous mode)#

The response if the sale is successful

RECURRING_SALE request sample#

Sample recurring sale request#

Request Example

curl -d "action=RECURRING_SALE&client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004&order_id=ORDER-12345&order_amount=1.99&order_description=Product&recurring_first_trans_id=aaaff66a-904f-11ea-833e-0242ac&recurring_token=d6dcb9e0-96b6-11ea-bbd1-0242ac120012&hash= a1a6de416405ada72bb47a49176471dc"https://test.apiurl.com -k

Sample response#

Response Example

{"action":"RECURRING_SALE","result":"SUCCESS","status":"SETTLED","order_id":"ORDER-12345","trans_id":"aaaff66a-904f-11ea-833e-0242ac1f0007","trans_date":"2012-04-03 16:02:01","descriptor":"test", "amount":"0.02","currency":"USD"}

CREDITVOID request sample#

Sample response#

Request Example

curl -d "action=CREDITVOID&client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004&trans_id=aaaff66a-904f-11ea-833e-0242ac&amount=10.00&hash=6b957fca41c353ac344fcad47f0cbf97"https://test.apiurl.com -k

Sample response#

Response Example

{"action":"CREDITVOID","result":"ACCEPTED","trans_id":"aaaff66a-904f-11ea-833e-0242ac","order_id":"ORDER-12345"}

Appendix C (Additional parameters)#

When using some connector services, it is necessary to send additional parameters in the SALE request. You can add specific parameters in the parameters object.
For more information, contact your manager.

Additional parameters - Set 1 (BNG)#

Parameter	Description	Values	Required field
`bnrg_installm_def`	Indicates the number of months that will elapse from the purchase until the total or partial charge is made to the cardholder's account (initial deferral). Possible values: `01` - one month `00` - no delay initial	numeric justified to 2 digits	+
`bnrg_installm_months`	Indicates the number of monthly payments in which the total amount of the transaction will be divided. Example: `03` - 3 months	numeric justified to 2 digits	+
`bnrg_installm_plan`	Indicates if the promotion It will be ́ with interest or without interest. Possible values: `03` - no interest `05` - with interest `07` - defer only initial .	numeric justified to 2 digits	+

Sample curl request

curl –d "action=SALE&client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004&order_id=ORDER12345&order_amount=1000.99&order_currency=MXN&order_description=Product&card_number=4111111111111111&card_exp_month=01&card_exp_year=2025&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=http://client.site.com/return.php&parameters[bnrg_installm_def]=00&parameters[bnrg_installm_months]=03&parameters[bnrg_installm_plan]=03&hash=2702ae0c4f99506dc29b5615ba9ee3c0" https://test.apiurl.com -k

Additional parameters - Set 1 (FCP)#

Parameter	Description	Values	Required field
`subjectId`	ID of an bank account from the partner	String	+
`bnrg_installm_months`	ID of one of the partner's clients	String	+

Sample curl request

curl –d "action=SALE&client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004&order_id=ORDER12345&order_amount=1000.99&order_currency=BRL&order_description=Product&card_number=4111111111111111&card_exp_month=01&card_exp_year=2025&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=http://client.site.com/return.php&parameters[subjectId]=7c698450-0a9c-456f-bd39-9f442a9744c7&parameters[toBankAccountId]=a1a1134a-32c6-442c-90c9-66b587d5be00&hash=2702ae0c4f99506dc29b5615ba9ee3c0" https://test.apiurl.com -k