S2S APM

Version: 1.4.1
Released: 2022/10/10

Introduction#

This document describes integration procedures and VIRTUAL PAYMENT GATEWAY protocol usage for e-commerce merchants.

VIRTUAL PAYMENT GATEWAY protocol implements acquiring payments (purchases) with using specific API interaction.

Integration Process#

Client Registration#

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

Data	Description
Callback URL	URL which will be receiving the notifications of the processing results of your request to Payment Platform
Contact e-mail	Client`s contact email
IP List	List of your IP addresses, from which requests to Payment Platform will be sent.

With all Payment Platform POST requests at Callback URL the Client 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.

Parameter	Description
CLIENT_KEY	Unique key to identify the account in Payment Platform (used as request parameter). In the administration platform this parameter corresponds 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

Payment Platform Interaction#

For the transaction you must send the server to server HTTPS POST request to the Payment Platform URL (PAYMENT_URL). In response Payment Platform will return the JSON (http://json.org/)) encoded string.

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 transaction
CREDITVOID	Creates REFUND transaction
CREDIT2VIRTUAL	Creates CREDIT2VIRTUAL transaction
GET_TRANS_STATUS	Gets status of transaction 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
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
PREPARE	Status is undetermined, final status will be sent in callback
REDIRECT	The transaction awaits SALE
SETTLED	Successful transaction
REFUND	Transaction for which refund was made
DECLINED	Not successful transaction

Transactions requests

SALE request#

Use SALE request to create a payment in the Payment Platform.

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	Limitations	Required
`action`	Action to perform (=SALE)	= SALE	+
`client_key`	Unique client key (CLIENT_KEY)		+
`channel_id`	Payment channel (Sub-account)	String up to 16 characters	-
`brand`	Brand through which the transaction is performed	String up to 36 characters(Appendix B)	+
`order_id`	Transaction ID in the Clients 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	+
`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_birth_date`	Customer's birthday	Date format is "YYYY-MM-DD"	-
`payer_ip`	IP-address of the Customer	XXX.XXX.XXX.XXX	+
`return_url`	URL to which Customer should be returned after operation in third-party system	String up to 1024 characters	+
`identifier`	Extra parameter for transaction. It could be token, account information, additional descriptor etc	String up to 255 characters	+
`hash`	Special signature to validate your request to Payment Platform	See Appendix A, Sale signature.	+

Response Parameters#

You will get JSON encoded string with transaction result.

Successful sale response

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

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

Redirect transaction response

Parameter	Description
`action`	SALE
`result`	REDIRECT
`status`	REDIRECT
`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 parameters
`redirect_method`	The method of transferring parameters (POST/GET)

Callback parameters#

Successful sale response

Parameter	Description
`action`	SALE
`result`	SUCCESS
`status`	SETTLED
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Client's system
`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
`hash`	Special signature to validate callback. See Appendix A, Callback signature.

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 Client's system
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Transaction date in the Payment Platform
`decline_reason`	Description of the cancellation of the transaction
`hash`	Special signature to validate callback. See Appendix A, Callback signature.

Redirect transaction response

Parameter	Description
`action`	SALE
`result`	REDIRECT
`status`	REDIRECT
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Client's system
`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 to validate callback. See Appendix A, Callback signature.

CREDIT2VIRTUAL request#

CREDIT2VIRTUAL request is used to create CREDIT2VIRTUAL transaction in Payment Platform.

This operation transfers money from merchants account to customer account.

If you want to send a payout 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`	CREDIT2VIRTUAL	CREDIT2VIRTUAL	+
`client_key`	Unique client key (CLIENT_KEY)		+
`channel_id`	Payment channel (Sub-account)	String up to 16 characters	-
`brand`	Brand through which the transaction is performed	String up to 36 characters	+
`order_id`	Order 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	+
`parameters`	Array of the parameters for specific brand	(Appendix B)	+
`hash`	Special signature to validate your request to Payment Platform	See Appendix A, Credit2Virtual signature.	+

Response Parameters#

You will get JSON encoded string with transaction result.

Successful response

Parameter	Description
`action`	CREDIT2VIRTUAL
`result`	SUCCESS
`status`	SETTLED
`order_id`	Order ID in the Client’s system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform

Response Example (Successful result)

{"action": "CREDIT2VIRTUAL","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`	CREDIT2VIRTUAL
`result`	DECLINED
`status`	DECLINED
`order_id`	Order 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": "CREDIT2VIRTUAL","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 procesing"}

Callback parameters#

Successful response

Parameter	Description
`action`	CREDIT2VIRTUAL
`result`	SUCCESS
`status`	SETTLED
`order_id`	Order ID in the Client’s system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`hash`	Special signature to validate callback. See Appendix A, Credit2Virtual callback signature

Response Example (Successful result)

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

Unsuccessful response

Parameter	Description
`action`	CREDIT2VIRTUAL
`result`	DECLINED
`order_id`	Order ID in the Client’s system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction ID in the Payment Platform
`decline_reason`	Description of the cancellation of the transaction
`hash`	Special signature to validate callback. See Appendix A, Credit2Virtual callback signature

Response Example (Unsuccessful result)

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

CREDITVOID request#

CREDITVOID request is used to complete REFUND transactions.

REFUND transaction is used to return funds to account, previously submitted by SALE transactions.

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

Request parameters#

Parameter	Description	Limitations	Required
`action`	Action to perform	= 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 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, Creditvoid signature.	+

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 response

Parameter	Description
`action`	CREDITVOID
`result`	SUCCESS
`status`	REFUND (full refund) / SETTLED (partial refund)
`order_id`	Transaction ID in the Client 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, Creditvoid signature.

Unsuccessful refund 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. See Appendix A, Creditvoid signature.

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
`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	See Appendix A, GET_TRANS_STATUS signature	+

Response parameters#

Parameter	Description
`action`	GET_TRANS_STATUS
`result`	SUCCESS
`status`	DECLINED/SETTLED
`order_id`	Order ID in the Client’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

Errors#

In case error you get synchronous response from Payment Platform:

Parameter	Description
`result`	ERROR
`error_message`	Error message

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:

Sale signature#

Hash is calculated by the formula:

md5(strtoupper(strrev(identifier + order_id + order_amount + order_currency + PASSWORD)));

Creditvoid signature#

Hash is calculated by the formula:

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

Credit2Virtual signature#

$hash = md5(strtoupper(strrev($order_id . $order_amount . $order_currency)) . $PASSWORD);

Credit2Virtual callback signature#

$hash = md5(strtoupper(strrev($trans_id . $order_id . $status)) . $ PASSWORD);

GET_TRANS_STATUS signature#

$hash = md5(strtoupper(strrev($trans_id)) . $ PASSWORD);

Callback signature#

Hash is calculated by the formula:

array_walk_recursive($params, static function (&$value) {    $value = strrev($value);});$params['hash'] = md5(strtoupper(convert($params) . PASSWORD));function convert($params){    foreach ($params as &$value) {        if (is_array($value)) {            $value = $this->convert($value);        }    }    ksort($params);    return implode($params);}