Integration flow

Version: 3.6.4
Released: 2025/09/30

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

Integration process

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.

⚠️ Pay attention

Note that the notification URL may be temporarily blocked due to consistently receiving timeouts in response to the callback. If five timeouts accumulate within five minutes for a merchant’s notification URL, it will be blocked for 15 minutes. During this block, all merchants associated with the URL will not receive notifications. The block automatically lifts after 15 minutes. Additionally, it is possible to manually unblock the URL through the admin panel by navigating to Configuration → Merchants → Edit Merchant. In this case, the block will be removed immediately. The timeout counter resets if a callback response is successfully processed. For instance, if there are four timeouts within five minutes but a successful response on the sixth minute, the counter resets.

⚠️ Pay attention

In the case of cascading, the logic for sending callbacks differs. If cascading is triggered for the order, you will receive callbacks for the first payment attempt, where the decline occurred and which caused the cascading, as well as for the last payment attempt, where the final status of the order (settled or declined) is determined. Additionally, for the last attempt, the callback will include only the final status. That is, callbacks regarding 3DS or redirects will not be sent. Callbacks for intermediate attempts (between the first decline and the last payment attempt) are not sent.

Definitions

Variable	Description	Value
`{{API_HOST}}`	Base URL for TESS APM	`https://api.tesspayments.com/post-va`

⚠️ Pay attention

If the required method is GET and the redirect_url contains query parameters, such as:
redirect_url=https://example.domain.com/?parameter=1

There are two possible approaches for implementing the redirect:

Option 1: Redirecting the customer by sending query parameters within the form inputs
Parse the query parameters from the redirect_url and pass them as input elements in an HTML form:

Example:
<form action="https://example.domain.com" method="GET">
 <input name="parameter" value="1">
 <input type="submit" value="Go">
</form>
Option 2: Redirect Using JavaScript
Use JavaScript to redirect the customer to the specified redirect_url with the query parameters:

Example:
document.location = 'https://example.domain.com/?parameter=1';

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

Protocol Mapping

It is necessary to check the existence of the protocol mapping before using the S2S integration. Merchants can’t make payments if the S2S APM protocol is not mapped.

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.

⚠️ Pay attention

The S2S (Server-to-Server) protocol requires requests to be sent with the following content type: Header:
Content-Type: application/x-www-form-urlencoded

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
VOID	Creates VOID transaction
CREDIT2VIRTUAL	Creates CREDIT2VIRTUAL transaction
DEBIT2VIRTUAL	Creates DEBIT transaction as a part of transfer flow
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
INIT	Additional action required from customer, final status will be sent in callback
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
VOID	Transaction for which void was made
REFUND	Transaction for which refund was made
PENDING	The payment has been initiated and additional actions are required from customer
DECLINED	Not successful transaction

Callback Events

⚠️ Pay attention

The callback will be sent with the following content type: application/x-www-form-urlencoded

Merchants receive callbacks when creating transactions with the following statuses:

Transaction	Status
SALE, CREDITVOID, DEBIT	SUCCESS, FAIL, WAITING, UNDEFINED
VOID, CREDIT2VIRTUAL	SUCCESS, FAIL, UNDEFINED

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	-
`crypto_network`	Blockchain network	String up to 50 characters. You can use an arbitrary value or choose one of the following: • ERC20 • TRC20 • BEP20 • BEP2 • OMNI • solana • polygon	-
`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. Format depends on currency. Send Integer type value for currencies with zero-exponent. Example: 1000 Send Float type value for currencies with exponents 2, 3, 4. Format for 2-exponent currencies: XX.XX Example: 100.99 Pay attention that currencies 'UGX', 'JPY', 'KRW', 'CLP' must be send in the format XX.XX, with the zeros after comma. Example: 100.00 Format for 3-exponent currencies: XXX.XXX Example: 100.999. Format for 4-exponent currencies: XXX.XXXX Example: 100.9999 ⚠️ Note!
`order_currency`	Currency	3 characters for fiat currencies	+
`order_description`	Description of the transaction (product name)	String up to 1024 characters	+
`identifier`	Extra parameter for transaction. It could be token, account information, additional descriptor etc. The value should be unique	String up to 255 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_house_number`	Customer's house or building number	String up to 9 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 40 characters	-
`payer_district`	Customer's district of 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. Both versions, IPv4 and IPv6, can be used. If you are sending IPv6, make sure the payment provider that processes the payments supports it.	XXX.XXX.XXX.XXX	+
`return_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)	-
`return_url`	URL to which Customer should be returned after operation in third-party system	String up to 1024 characters	+
`parameters`	Array of the parameters for specific brand	(Appendix B)	+
`custom_data`	Array with the custom data This block duplicates the arbitrary parameters that were passed in the payment request	Format: `custom_data [param1]: value1` `custom_data [param2]: value2` `custom_data [paramN]: valueN`	-
`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
`amount`	Order amount
`currency`	Currency

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
`amount`	Order amount
`currency`	Currency

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 or GET)
`amount`	Order
`currency`	Currency

Undefined sale response

Parameter	Description
`action`	SALE
`result`	UNDEFINED
`status`	REDIRECT / PREPARE
`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`	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
`amount`	Order amount
`currency`	Currency

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
`exchange_rate`	Rate used to make exchange
`exchange_rate_base`	The rate used in the double conversion to convert the original currency to the base currency
`exchange_currency`	Original currency
`exchange_amount`	Original amount
`hash`	Special signature to validate callback. See Appendix A, Callback signature.
`amount`	Order amount
`currency`	Currency
`custom_data`	Object with the custom data. This block duplicates the arbitrary parameters that were passed in the payment request
`connector_name` *	Connector's name (Payment Gateway)
`rrn` *	Retrieval Reference Number value from the acquirer system
`approval_code` *	Approval code value from the acquirer system
`gateway_id` *	Gateway ID – transaction identifier provided by payment gateway
`extra_gateway_id` *	Extra Gateway ID – additional transaction identifier provided by payment gateway.
`merchant_name` *	Merchant Name
`mid_name` *	MID Name
`issuer_country` *	Issuer Country
`issuer_bank` *	Issuer Bank
`extended_data` *	Transaction extended data
`brand` *	Payment method brand used in the transaction
`arn` *	Acquirer Reference Number value from the acquirer system

* The parameters are included if the appropriate setup is configured in the admin panel (see “Add Extended Data to Callback” block in the Configurations -> Protocol Mappings section).

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.
`amount`	Order amount
`currency`	Currency
`custom_data`	Object with the custom data. This block duplicates the arbitrary parameters that were passed in the payment request

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 or GET)
`hash`	Special signature to validate callback. See Appendix A, Callback signature.
`amount`	Order amount
`currency`	Currency
`custom_data`	Object with the custom data. This block duplicates the arbitrary parameters that were passed in the payment request

Undefined sale response

Parameter	Description
`action`	SALE
`result`	UNDEFINED
`status`	REDIRECT / PREPARE
`order_id`	Transaction ID in the Merchant's system system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`descriptor`	TDescriptor from the bank, the same as cardholder will see in the bank statement
`amount`	Order amount
`currency`	Order currency
`custom_data`	Object with the custom data. This block duplicates the arbitrary parameters that were passed in the payment request
`hash`	Special signature, used to validate callback, see Appendix A, Formula 2

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.	Format depends on currency. Send Integer type value for currencies with zero-exponent. Example: 1000 Send Float type value for currencies with exponents 2, 3, 4. Format for 2-exponent currencies: XX.XX Example: 100.99 Pay attention that currencies 'UGX', 'JPY', 'KRW', 'CLP' must be send in the format XX.XX, with the zeros after comma. Example: 100.00 Format for 3-exponent currencies: XXX.XXX Example: 100.999. Format for 4-exponent currencies: XXX.XXXX Example: 100.9999	-
`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 Merchant'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 Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`creditvoid_date`	Date of the refund/reversal
`amount`	Amount of refund
`connector_name` *	Connector's name (Payment Gateway)
`rrn` *	Retrieval Reference Number value from the acquirer system
`approval_code` *	Approval code value from the acquirer system
`gateway_id` *	Gateway ID – transaction identifier provided by payment gateway
`extra_gateway_id` *	Extra Gateway ID – additional transaction identifier provided by payment gateway.
`merchant_name` *	Merchant Name
`mid_name` *	MID Name
`issuer_country` *	Issuer Country
`issuer_bank` *	Issuer Bank
`hash`	Special signature, used to validate callback. See Appendix A, Creditvoid signature.

* The parameters are included if the appropriate setup is configured in the admin panel (see “Add Extended Data to Callback” block in the Configurations -> Protocol Mappings section).

Unsuccessful refund response

Parameter	Description
`action`	CREDITVOID
`result`	DECLINED
`status`	SETTLED
`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, Creditvoid signature.

Undefined refund response

Parameter	Description
`action`	CREDITVOID
`result`	UNDEFINED
`status`	SETTLED
`order_id`	Transaction ID in the Transaction ID in the Merchant's system
`trans_id`	Transaction ID in the Payment Platform
`creditvoid_date`	Transaction date in the Payment Platform
`amount`	Amount of refund
`hash`	Special signature, used to validate callback, see Appendix A, Formula 2

VOID request

The VOID request is used to cancel the operation which was performed the same financial day (Applicable if bank supports the feature).

The cancellation is possible for the SALE operation.

The VOID request is allowed for the payments in SETTLED status only.

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

Request parameters

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

Response parameters

You will get JSON encoded string with transaction result.

Successful void response

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

Unsuccessful void response

Parameter	Description
`action`	VOID
`result`	DECLINED
`status`	SETTLED
`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`	The reason why the transaction was declined

Undefined void response

Parameter	Description
`action`	VOID
`result`	UNDEFINED
`status`	SETTLED
`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

Callback parameters

Successful void response

Parameter	Description
`action`	VOID
`result`	SUCCESS
`status`	SETTLED
`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
`connector_name` *	Connector's name (Payment Gateway)
`rrn` *	Retrieval Reference Number value from the acquirer system
`approval_code` *	Approval code value from the acquirer system
`gateway_id` *	Gateway ID – transaction identifier provided by payment gateway
`extra_gateway_id` *	Extra Gateway ID – additional transaction identifier provided by payment gateway.
`merchant_name` *	Merchant Name
`mid_name` *	MID Name
`issuer_country` *	Issuer Country
`issuer_bank` *	Issuer Bank
`hash`	Special signature, used to validate callback, see Appendix A, Formula 2

* The parameters are included if the appropriate setup is configured in the admin panel (see “Add Extended Data to Callback” block in the Configurations -> Protocol Mappings section).

Unsuccessful void response

Parameter	Description
`action`	VOID
`result`	DECLINED
`status`	SETTLED
`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`	The reason why the transaction was declined
`hash`	Special signature, used to validate callback, see Appendix A, Formula 2

Undefined void response

Parameter	Description
`action`	VOID
`result`	UNDEFINED
`status`	SETTLED
`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
`hash`	Special signature, used to validate callback, see Appendix A, Formula 2

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`	REDIRECT / PREPARE / DECLINED / SETTLED / REFUND / VOID
`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
`extended_data` *	Transaction extended data
`arn` *	Acquirer Reference Number value from the acquirer system

* The parameters are included if the appropriate setup is configured in the admin panel (see “Add Data to” block in the Configurations -> Protocol Mappings section).

Errors

In case error you get synchronous response from Payment Platform:

Parameter	Description
`result`	ERROR
`error_message`	Error message

Testing

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

Customer's email	Testing / Result
success@gmail.com	This email must be used for testing successful sale. Response on successful SALE request: `{action: SALE, result: SUCCESS, status: SETTLED}`
fail@gmail.com	This email date must be used for testing unsuccessful sale Response on unsuccessful SALE request: `{action: SALE, result: DECLINED, status: DECLINED}`

Debit Card NAPS

Use the following test data to emulate the different scenarios.

For Card

Card data:

Card number 4215375500883243
Expiry Date 06/2028
CVV2 123
Pin 1324

For Himyan

Card number 6399502253289053
Expiry Date 07/2029
CVV2 186
Pin 123456

OM Wallet

Use the following test data to emulate the different scenarios.

Wallet data:

Wallet number +97487778777
Mpin 1212
OTP 1234

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: