Sale Request

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

info

Depending on the payment method, the list of fields can also be expanded. For example, if the account number needs to be collected during the interaction. Go to (Supported brands)[/docs/guides/s2s_apm/s2s_apm_brands] for more information.

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 Merchant's system	String up to 255 characters	+
order_amount	The amount of the transaction. For purchase operation with crypto: Do not send parameter at all if you want to create a transaction with an unknown amount - for cases when the amount is set by the payer outside the merchant site (for example, in an app). As well, you have to omit "amount" parameter for hash calculation for such cases.	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! For crypto currencies use the exponent as appropriate for the specific currency.	+
order_currency	Currency	3 characters for fiat currencies and from 3 to 6 characters for crypto 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. This is optional if crypto currency is used	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_phone_country_code	Country calling code of the payer’s phone number	String; length depends on the country	-
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.

INIT transaction response (for crypto flow)

Parameter	Description
action	SALE
result	SUCCESS
status	PENDING
order_id	Transaction ID in the Merchant's system
trans_id	Transaction ID in the Payment Platform
trans_date	Transaction date in the Payment Platform
descriptor	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 Customer's support web-site
amount	Order amount
currency	Currency
crypto_address	Public address of a cryptocurrency wallet
crypto_network	Blockchain network where the transaction is taking place

Successful sale response

Parameter	Description
action	SALE
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
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 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
amount	Order amount
currency	Currency

Redirect transaction response

Parameter	Description
action	SALE
result	REDIRECT
status	REDIRECT
order_id	Transaction ID in the Merchant's system
trans_id	Transaction ID in the Payment Platform
trans_date	Transaction date in the Payment Platform
redirect_url	URL to which the merchant should redirect the Customer
redirect_params	Array of specific parameters
redirect_method	The method of transferring parameters (POST or GET)
amount	Order amount
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

INIT transaction response (for crypto flow)

Parameter	Description
action	SALE
result	INIT
status	PENDING
order_id	Order 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 Customer's support web-site
amount	Order amount
currency	Currency

Successful sale response

Parameter	Description
action	SALE
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
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 Merchant's system
trans_id	Transaction ID in the Payment Platform
trans_date	Transaction date in the Payment Platform
descriptor	Descriptor from the bank, the same as cardholder will see in the bank statement
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 Merchant's system
trans_id	Transaction ID in the Payment Platform
trans_date	Transaction date in the Payment Platform
redirect_url	URL to which the merchant 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
trans_id	Transaction ID in the Payment Platform
trans_date	Transaction date in the Payment Platform
descriptor	Descriptor from the bank, the same as cardholder will see in the bank statement
amount	Order amount
currency	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