Debit

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 40 characters	-
payer_zip	ZIP-code of the Customer	String up to 10 characters	-
payer_email	Customer’s email	String up to 255 characters	-
payer_phone	Customer’s phone	String up to 32 characters	-
payer_phone_country_code	Country calling code of the payer’s phone number	Digits, up to 10 characters. A hyphen is allowed for composite codes, for example 1-684	-
payer_ip	IP-address of the Customer	XXX.XXX.XXX.XXX	+
payer_language	Language of the platform-hosted pages shown to the Customer during the payment, such as the interaction template and the Thank You page. The value is case-insensitive and is not validated: a code that is not on the list falls back to English. If the parameter is omitted, the Checkout Default Language from the Protocol Mapping settings is used. If that is not set either, the language is taken from the Customer's browser.	One of: en, sp, ar, az, fr, nb, zh, zh-TW, kk, de, it, hr, cs, hu, pl, pt, ro, ja, nl, bg, ru	-
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	+

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

Callback parameters

Successful response

Parameter	Description
action	DEBIT2VIRTUAL
result	SUCCESS
status	REDIRECT / 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
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, Callback 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 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, Callback signature

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, Callback signature

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 40 characters	-
payer_zip	ZIP-code of the Customer	String up to 10 characters	-
payer_email	Customer’s email	String up to 255 characters	-
payer_phone	Customer’s phone	String up to 32 characters	-
payer_phone_country_code	Country calling code of the payer’s phone number	Digits, up to 10 characters. A hyphen is allowed for composite codes, for example 1-684	-
payer_ip	IP-address of the Customer	XXX.XXX.XXX.XXX	+
payer_language	Language of the platform-hosted pages shown to the Customer during the payment, such as the interaction template and the Thank You page. The value is case-insensitive and is not validated: a code that is not on the list falls back to English. If the parameter is omitted, the Checkout Default Language from the Protocol Mapping settings is used. If that is not set either, the language is taken from the Customer's browser.	One of: en, sp, ar, az, fr, nb, zh, zh-TW, kk, de, it, hr, cs, hu, pl, pt, ro, ja, nl, bg, ru	-
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	+

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

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
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, Callback 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 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, Callback signature

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	+

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

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
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, Callback 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 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, Callback signature

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, Callback signature