S2S VPG #

Version: 3.3.4
Released: 2024/07/01

Copyrighted by lddPay

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.

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

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
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
VOID	Transaction for which void was made
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	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	+
order_currency	Currency	3-letter code	+
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	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	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

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

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	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	+
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 C)	+
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
amount	Order amount
currency	Currency

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

Undefined response

Parameter	Description
action	CREDIT2VIRTUAL
result	UNDEFINED
status	PREPARE
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
amount	Order amount
currency	Currency

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

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

Undefined response

Parameter	Description
action	CREDIT2VIRTUAL
result	UNDEFINED
status	PREPARE
order_id	Order 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
amount	Order amount
currency	Currency

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
hash	Special signature, used to validate callback. See Appendix A, Creditvoid signature.

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.

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
hash	Special signature, used to validate callback, see Appendix A, Formula 2

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

DEBIT request #

Use debit actions to create debit transactions. When conducting a debit transaction, merchants can utilize commissions for payments by configuring the appropriate settings in the admin panel.

Debit transactions can be executed in two ways:

One-step debit

This option enables payment processing with a single request – DEBIT2VIRTUAL. If commissions are set for debits, they will be applied immediately upon payment. The commission amount can be viewed in the callback (commission parameter).

Two-steps debit

This option involves initiating the debit using the DEBIT2VIRTUAL_CALC request first, followed by confirming the operation through the DEBIT2VIRTUAL_COMPLETE request. In this scenario, if commissions are configured for debits, the commission amount will be returned in the response (commission parameter) after executing the DEBIT2VIRTUAL_CALC request.

DEBIT2VIRTUAL request parameters #

Use DEBIT2VIRTUAL action to create debit transaction in one step.

Parameter	Description	Values	Required
action	Action that you want to perform. Fixed value.	DEBIT2VIRTUAL	+
client_key	Unique key (CLIENT_KEY)	UUID format value	+
order_id	Transaction ID in the Merchants system	String up to 255 characters	+
order_amount	The amount of the transaction	Numbers in the form XXXX.XX	+
order_currency	Currency	3-letter code	+
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.	String up to 255 characters	+
brand	Brand through which the transaction is performed	String up to 36 characters	+
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 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 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	+
payer_return_url	Customer return URL	String up to 256 characters	+
hash	Special signature to validate your request to Payment Platform	See Appendix A, Debit signature	+

DEBIT2VIRTUAL response parameters #

You will get JSON encoded string with transaction result. If your account supports 3D-Secure, transaction result will be sent to your Notification URL.

Successful response

Parameter	Description
action	DEVIT2VIRTUAL
result	SUCCESS
status	3DS / REDIRECT / 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
descriptor	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction: total_amount = amount + commission

Unsuccessful response

Parameter	Description
action	DEBIT2VIRTUAL
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 payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction
decline_reason	The reason why the transaction was declined

Undefined response

Parameter	Description
action	DEVIT2VIRTUAL
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	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Order currency
commission	Commission for transaction
total_amount	Total amount for transaction: total_amount = amount + commission

DEBIT2VIRTUAL callback parameters #

Successful response

Parameter	Description
action	DEBIT2VIRTUAL
result	SUCCESS
status	REDRIECT / 3DS / 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
descriptor	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction: total_amount = amount + commission
hash	Special signature, used to validate callback, see Appendix A, Formula 2

Unsuccessful response

Parameter	Description
action	DEBIT2VIRTUAL
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 payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction: total_amount = amount + commission
decline_reason	Description of the cancellation of the transaction
hash	Special signature, used to validate callback, see Appendix A, Formula 2

Undefined response

Parameter	Description
action	DEBIT2VIRTUAL
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	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Order currency
commission	Commission for transaction
total_amount	Total amount for transaction: total_amount = amount + commission
hash	Special signature, used to validate callback, see Appendix A, Formula 2

DEBIT2VIRTUAL_CALC request parameters #

Use DEBIT2VIRTUAL_CALC action to initiate DEBIT transaction and to get commission value.

Parameter	Description	Values	Required
action	Action that you want to perform. Fixed value.	DEBIT2VIRTUAL_CALC	+
client_key	Unique key (CLIENT_KEY)	UUID format value	+
order_id	Transaction ID in the Merchants system	String up to 255 characters	+
order_amount	The amount of the transaction	Numbers in the form XXXX.XX	+
order_currency	Currency	3-letter code	+
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.	+
brand	Brand through which the transaction is performed	String up to 36 characters	+
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 customer’s address	String up to 255 character	–
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	+
payer_return_url	Customer return URL	String up to 256 characters	+
hash	Special signature to validate your request to Payment Platform	See Appendix A, Debit signature	+

DEBIT2VIRTUAL_CALC response parameters #

You will get JSON encoded string with transaction result.

Successful response

Parameter	Description
action	DEBIT2VIRTUAL_CALC
result	SUCCESS
status	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	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction: total_amount = amount + commission

Unsuccessful response

Parameter	Description
action	DEBIT2VIRTUAL_CALC
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 payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction
decline_reason	The reason why the transaction was declined

DEBIT2VIRTUAL_CALC callback parameters #

Successful response

Parameter	Description
action	DEBIT2VIRTUAL_CALC
result	SUCCESS
status	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	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction
hash	Special signature, used to validate callback, see Appendix A, Formula 2

Unsuccessful response

Parameter	Description
action	DEBIT2VIRTUAL_CALC
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 payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction
decline_reason	Description of the cancellation of the transaction
hash	Special signature, used to validate callback, see Appendix A, Formula 2

DEBIT2VIRTUAL_COMPLETE request parameters #

Use DEBIT2VIRTUAL_COMPLETE action to confirm initiated debit transaction.

Parameter	Description	Values	Required field
action	Action that you want to perform. Fixed value.	DEBIT2VIRTUAL_COMPLETE	+
client_key	Unique key (CLIENT_KEY)	UUID format value	+
trans_id	Initiated transfer transaction ID in the Payment Platform	UUID format value	+
hash	Special signature to validate your request to Payment Platform	See Appendix A, Complete Debit signature	+

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

Successful response

Parameter	Description
action	DEBIT2VIRTUAL_COMPLETE
result	SUCCESS
status	3DS / REDIRECT / 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
descriptor	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction

Unsuccessful response

Parameter	Description
action	DEBIT2VIRTUAL_COMPLETE
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 payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction
decline_reason	The reason why the transaction was declined

Undefined response

Parameter	Description
action	DEBIT2VIRTUAL_COMPLETE
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	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Order currency
commission	Commission for transaction
total_amount	Total amount for transaction: total_amount = amount + commission

DEBIT2VIRTUAL_COMPLETE callback parameters #

Successful response

Parameter	Description
action	DEBIT2VIRTUAL
result	SUCCESS
status	3DS / REDIRECT / 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
descriptor	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction
hash	Special signature, used to validate callback, see Appendix A, Formula 2

Unsuccessful response

Parameter	Description
action	DEBIT2VIRTUAL
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 payer will see in the bank statement
amount	Order amount
currency	Currency
commission	Commission for transaction
total_amount	Total amount for transaction
decline_reason	Description of the cancellation of the transaction
hash	Special signature, used to validate callback, see Appendix A, Formula 2

Undefined response

Parameter	Description
action	DEBIT2VIRTUAL
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	Descriptor from the bank, the same as payer will see in the bank statement
amount	Order amount
currency	Order currency
commission	Commission for transaction
total_amount	Total amount for transaction: total_amount = amount + commission
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

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}

Supported brands #

Use the following brand`s names as value for brand parameter in the requests:

applepay (see Appendix B for Sale operation details)
googlepay (see Appendix B for Sale operation details)
paypal
sepa
stripe-js

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

Void signature #

Hash is calculated by the formula:

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

Credit2Virtual signature #

Hash is calculated by the formula:

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

Debit signature #

Hash is calculated by the formula:

_md5(strtoupper(strrev(identifier + order_id + order_amount + order_currency + PASSWORD)));_

Complete Debit signature #

Hash is calculated by the formula:

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

GET_TRANS_STATUS signature #

Hash is calculated by the formula:

$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);
}

Sale callback signature #

Hash calculation for notification in S2S VPG based on the next formula:
• output array has to be sorted alphabetically;
• joint all values;
• applying uppercase;

For example, for callback like this:

result=SUCCESS
amount=9.22
transactions=[ctrans1 = 123, atrans2 =32, itrans2 =325]

formula will be looking like this:

hash = reverse(action) + reverse(amount) + reverse(result) + reverse(transactions.atrans2) + reverse(transactions.ctrans1) + reverse(transactions.itrans2) + PASSWORD

and string_result:

string_result = ELASSSECCUS22.923321523PASSWORD

and hash:

hash = md5(string_result)

Credit2Virtual callback signature #

Hash is calculated by the formula:

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

Appendix B #

---

You have to add to your SALE request specific list of parameters which is determined by the value for the brand parameter.

You should get additional information from account manager.

To simulate success scenario use identifier parameter value success@gmail.com and fail@gmail.com for decline.

Apple Pay #

To provide the payers with the possibility of Apple Pay payments you can connect to the Checkout or work directly via S2S VPG protocol.

If you work via Checkout page you don’t need any additional development on your side.

If you work via S2S VPG protocol, you must pass you must be able to obtain Apple Pay payment token that must be passed in the SALE request.

Regardless of the protocol you have to make settings in the admin panel and set the following configurations:

• Merchant Identifier, Country and Shop Name – according to the merchant’s data from Apple Pay Developper account
• Certificate and Private Key – generated Apple Pay certificate and private key
• Merchant Capabilities and Supported Networks – configurations for Apple Pay payments
• Processing Private Key – private key that uses for payment token decryption (requires if payment provider supports).

⚠️ Pay attention

Before using Apple Pay via S2S VPG protocol, you should review next section carefully. There is a description on how you can obtain Apple Pay payment token (it refers to the official Apple Pay documentation)

1. Each payment must be checked for Apple Pay accessibility
2. Show Apple Pay button to your payers
3. Validate the merchant identity
4. Provide a payment request and create a session
5. Receive Apple Pay payment token (paymentData object)

After you implement Apple Pay payment tokens generation on your site, you need to pass for the SALE request:

• brand = applepay
• parameters[paymentToken] – Apple Pay payment token

We also recommend checking out the demo provided by Apple for Apple Pay: https://applepaydemo.apple.com/

Google Pay #

To provide the payers with the possibility of Google Pay™ payment you can connect to the Checkout or work directly via S2S VPG protocol. Before using googlepay payment method, you should review this section carefully to meet all the Google Pay™ requirements:

1. Overview the documentation on Google Pay Integration first:
   • for sites – Google Pay Web developer documentation
   • for Android app – Google Pay Android developer documentation
2. Make sure you complete all the items on the integration checklist:
   • for sites – Google Pay Web integration checklist
   • for Android app – Google Pay Android integration checklist
3. To brand your site with Google Pay elements, you must meet the requirements:
   • for sites – Google Pay Web Brand Guidelines
   • for Android app – Google Pay Android brand guidelines
4. The merchants must adhere to the Google Pay APIs Acceptable Use Policy and accept the terms that the Google Pay API Terms of Service defines.

To work with Google Pay™ payments through gateway, you need to make settings in the admin panel. You can set the following configurations:
• choose the environment: TEST or PRODUCTION
• specify “Allowed Auth Method” – PAN_ONLY or CRYPTOGRAM_3DS
• determine “Supported Networks” – MASTERCARD, VISA, AMEX, DISCOVER, JCB
These configuration will be applied and used when platform interacts with Google Pay.
If you are using Checkout integration to work with googlepay payment method, it requires no additional code implementation.

If you are using S2S VPG integration to work with googlepay payment method, you need to pass the additional parameters in the SALE request:
• brand = googlepay
• parameters[googlepay_token] – Google Pay payment token.
To obtain Google Pay payment token you should get the PaymentData according to the Google Pay API Integration documentation (see the links above).
Pass the following parameters to receive PaymentData:
• allowPaymentMethods: CARD
• tokenizationSpecification = { “type”: “PAYMENT_GATEWAY”}
• allowedCardNetworks = [‘MASTERCARD’, ‘VISA’, ‘AMEX’, ‘DISCOVER’, ‘JCB’];
• allowedCardAuthMethods = [‘PAN_ONLY’, ‘CRYPTOGRAM_3DS’];
• gateway = value provided by your support manager
• gatewayMerchantId = CLIENT_KEY (API key)

As a result you receive you will be returned a dataset with PaymentData.token object contains data that you need add to the SALE request as parameters[googlepay_token] parameter.

⚠️ Pay attention

in the case of PAN_ONLY, the responsibility for passing 3ds is transferred to the acquirer, through which the payment is processed