Payment Requests¶

Note: Parameters marked with an asterisk (*) are required.

Creating a Payment Request¶

Request¶

POST example.com/api/merchant/"merchant"/create_pay_in

Headers¶

Name	Value
Content-Type*	application/json

Request Parameters¶

Name	Type	Format	Description
order_id*	string max: 255		Request ID in your system
payment_method*	string	enum (card, sbp, score, iban)	Payment type (card, SBP, bank account, IBAN)
fiat_amount*	string		Request amount in fiat currency
fiat_currency*	string	enum	Order currency
timeout	int		Payment timeout in minutes
bank	string	enum ()	Preferred recipient bank
sign*	string		Request signature
success_callback_url*	string max: 512		URL for successful payment notification
error_callback_url	string max: 512		URL for payment cancellation by the platform
type_traffic	string	enum (etd, trusted)	Traffic type
customer	string max: 128		Customer identifier
order_description	string max: 8000		Order description

Request Signature Generation Method:¶

The signature for creating a payment request is generated by calculating the SHA256 hash of the following string:

order_id : fiat_amount : fiat_currency : payment_method : sign_key

Signature generation example:

String to sign:

123456789:1500.00:rub:sbp:test

SHA256 result:

76c5beb80bb2ea3fd0f67ad8325b0c68ae70d75cf926b77c0f1ac18c05eecfbb

Request Example¶

{
  "order_id": "123456789",
  "payment_method": "sbp",
  "fiat_amount": "1500.00",
  "fiat_currency": "rub",
  "timeout": 30,
  "bank": "sber",
  "sign": "76c5beb80bb2ea3fd0f67ad8325b0c68ae70d75cf926b77c0f1ac18c05eecfbb",
  "success_callback_url": "https://yourwebsite.com/success",
  "error_callback_url": "https://yourwebsite.com/error",
  "customer": "CUST12345",
  "order_description": "Payment for goods in online store"
}

Response Parameters¶

Name	Type	Format	Description
internal_transaction_id*	string max: 72		Internal transaction ID in the system
order_id*	string max: 255		Request ID in your system
payment_method*	string	enum (card, sbp, score, iban)	Payment type (card, SBP, bank account, IBAN)
fiat_amount*	string		Request amount
fiat_currency*	string		Order currency. Available values are listed in the regions list
number_score	string (20)		Bank account number (for bank account payments)
number_card	string (16)		Card number (for card payments)
phone_number	string min 11 max:13		Phone number (for SBP payments)
iban_number	string max: 34		IBAN (for IBAN payments)
bank*	string max: 64		Recipient bank code
bank_name*	string max: 72		Recipient bank name (full, as string)
bik	string		Recipient BIC (only for bank account payments)
full_name	string max: 128		Recipient full name
reject_callback_url*	string max: 512		URL for payment cancellation by the merchant
summ_transaction*	string		Transaction amount (number with 2 decimal places)
currency*	string		Currency code
usdt_amount*	string		Amount in USDT
merchant_spent_usdt*	string		USDT amount credited to merchant (4 decimal places)
exchange_rate*	string		Exchange rate (4 decimal places)
sign*	string		Response signature

Response Signature Generation Method:¶

The response signature is generated by calculating the SHA256 hash of the following string:

order_id : summ_transaction : number_score/number_card/phone_number/iban_number : sign_key

One of the parameters number_score/number_card/phone_number/iban_number is selected depending on the payment method used.

Possible Errors in Response¶

Text	Value
overloading requisite	Requisite overload, try creating a request for a different amount, with a different payment method, or wait
this payment method is disabled for your merchant	This payment method is disabled for your merchant
unexpected error	Unexpected error

Response Example¶

200Error 400 and other 4xx

{
  "ok": true,
  "internal_transaction_id": "TRX-20240215-093045-987654321098",
  "order_id": "123456789",
  "payment_method": "sbp",
  "fiat_amount": "1500.00",
  "fiat_currency": "rub",
  "summ_transaction": "1500.00",
  "currency": "rub",
  "usdt_amount": "15.8765",
  "merchant_spent_usdt": "15.2500",
  "exchange_rate": "98.2472",
  "number_card": "1234567890123456",
  "bank": "sber",
  "bank_name": "Sber",
  "full_name": "Ivanov Ivan Ivanovich",
  "reject_callback_url": "https://yourwebsite.com/reject",
  "sign": "0df855e39b7910879cf2e91365ac06008a525f25e15f2f36575158342aa8f280"
}

{
  "ok": false,
  "error": "message"
}

Payment Request Confirmation/Cancellation by Platform¶

Description: This request is a callback from the platform when a request is cancelled or confirmed. The request is sent by the platform to the specified merchant URL (success_callback_url or error_callback_url) to notify about request status changes.

Request¶

POST error_callback_url

or

POST success_callback_url

Headers¶

Name	Value
Content-Type*	application/json

Request Parameters¶

Name	Type	Format	Description
order_id*	string max: 255		Request ID in your system
standart_sign*	string		Standard signature
type*	string	enum (pay_in)	Operation type
status*	string	enum (successful, rejected_timeout, rejected_merchant, rejected_gate)	Request status (successful - success, rejected_timeout - rejected by timeout, rejected_merchant - rejected by merchant, rejected_gate - rejected by platform support)
fiat_amount*	string		Request amount in fiat currency
usdt_amount*	string		Request amount in USDT
merchant_spent_usdt*	string		USDT amount credited to merchant
fiat_currency*	string		Fiat currency code
exchange_rate*	string		Exchange rate
payment_method*	string	enum (card, sbp, score, iban)	Payment type (card, SBP, bank account, IBAN)
created_at*	string	ISO 8601	Request creation date and time
updated_at*	string	ISO 8601	Request update date and time
old_fiat_amount	string		Previous request amount (only when amount is changed)
new_fiat_amount	string		New request amount (only when amount is changed)
number_card	string		Card number (only provided when payment_method = card)
phone_number	string		Phone number (only provided when payment_method = sbp)
number_score	string		Bank account number (only provided when payment_method = score)
iban_number	string		IBAN (only provided when payment_method = iban)
full_name	string		Recipient full name
bank_name*	string		Recipient bank name

Note: 1. For integration convenience, when confirming/cancelling a request, the ID can be passed both in the URL and in the request parameters. On your side, you can actually use only one of the methods for receiving the ID. 2. The old_fiat_amount and new_fiat_amount fields are only provided if the request amount was changed. 3. Only one of the payment details fields (number_card, phone_number, number_score, iban_number) is provided depending on the payment method.

Request Example¶

{
  "order_id": "123456789",
  "standart_sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "type": "pay_in",
  "status": "successful",
  "fiat_amount": "5000.00",
  "usdt_amount": "49.8765",
  "merchant_spent_usdt": "49.2500",
  "fiat_currency": "rub",
  "exchange_rate": "100.2472",
  "payment_method": "card",
  "created_at": "2024-02-15T09:30:45Z",
  "updated_at": "2024-02-15T09:45:12Z",
  "number_card": "4276345439581234",
  "phone_number": null,
  "number_score": null,
  "iban_number": null,
  "full_name": "Ivanov Ivan Ivanovich",
  "bank_name": "Sberbank"
}

Request Example with Amount Change¶

{
  "order_id": "123456789",
  "standart_sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "type": "pay_in",
  "status": "successful",
  "fiat_amount": "5000.00",
  "usdt_amount": "49.8765",
  "merchant_spent_usdt": "49.2500",
  "fiat_currency": "rub",
  "exchange_rate": "100.2472",
  "payment_method": "card",
  "created_at": "2024-02-15T09:30:45Z",
  "updated_at": "2024-02-15T09:45:12Z",
  "old_fiat_amount": "4800.00",
  "new_fiat_amount": "5000.00",
  "number_card": "4276345439581234",
  "phone_number": null,
  "number_score": null,
  "iban_number": null,
  "full_name": "Ivanov Ivan Ivanovich",
  "bank_name": "Sberbank"
}