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, qr)	Payment type (card, SBP, bank account, IBAN, QR code)
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
include_qr_base64	boolean		Return the QR code in the response body as base64. Only applies when `payment_method = qr`, ignored for other methods. Defaults to `false`
redirect	boolean		Request redirect mode (return of `redirect_url`). Defaults to `false`. Works only if redirect is enabled
payment_success_url	string max: 512		URL where the payment page returns the client after a successful payment. Required when `redirect: true`. Not to be confused with `success_callback_url` (S2S notification)
payment_failure_url	string max: 512		URL where the payment page returns the client after a failure/cancellation. Required when `redirect: true`. Not to be confused with `error_callback_url` (S2S notification)

Redirect mode (optional)

In addition to the standard response with payment requisites, the platform can return a ready-to-use link to the payment page (redirect_url) to which you redirect the client. The link is returned only if redirect is enabled and redirect: true is passed in the request together with the required payment_success_url / payment_failure_url. The response with requisites remains the default — redirect only complements it.

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, qr)	Payment type (card, SBP, bank account, IBAN, QR code)
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)
qr_file_id	int		QR code file identifier in the system (for QR code payments)
qr_file_url	string max: 512		Ready-to-use URL for retrieving the QR code file (for QR code payments)
qr_data_uri	string	data-URI	QR code as base64 (only when `payment_method = qr` and `include_qr_base64 = true`)
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)
redirect*	boolean		Redirect request indicator
redirect_url	string max: 512		Ready-to-use link to the payment page. Only for redirect requests
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/qr_file_id : sign_key

One of the parameters number_score/number_card/phone_number/iban_number/qr_file_id is selected depending on the payment method used. For payment_method = qr the signature includes qr_file_id; the qr_file_url, qr_data_uri and redirect_url fields are not part of the signature.

Note on QR code payments: when payment_method = qr, the QR code itself is the payment requisite, therefore the bank, bank_name and full_name fields are not returned in the response.

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
Redirect mode is not enabled for this merchant, currency and payment method	Redirect mode is not enabled; contact platform support to enable it
payment_success_url and payment_failure_url are required in redirect mode	Both URLs are required in redirect mode
Invalid redirect value	An unrecognized value was passed for the `redirect` flag
payment_success_url must be a string / payment_failure_url must be a string	The URL was not passed as a string
payment_success_url exceeds the allowed length (512 characters)	The URL is longer than 512 characters (same for `payment_failure_url`)

Response Example¶

200200 (QR code payment)200 (redirect mode)Error 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": true,
  "internal_transaction_id": "TRX-20240215-093045-987654321098",
  "order_id": "123456789",
  "payment_method": "qr",
  "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",
  "qr_file_id": 42,
  "qr_file_url": "https://example.com/api/merchant/your_merchant/qr_file/42",
  "qr_data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAywAAAMy...",
  "reject_callback_url": "https://yourwebsite.com/reject",
  "sign": "0df855e39b7910879cf2e91365ac06008a525f25e15f2f36575158342aa8f280"
}

Note: the qr_data_uri field is only present if include_qr_base64 = true was passed in the request. The value is a data-URI and can be placed directly into the src attribute of an <img> tag.

{
  "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",
  "phone_number": "79001234567",
  "bank": "sber",
  "bank_name": "Sber",
  "full_name": "Ivanov Ivan Ivanovich",
  "reject_callback_url": "https://yourwebsite.com/reject",
  "sign": "0df855e39b7910879cf2e91365ac06008a525f25e15f2f36575158342aa8f280",
  "redirect": true,
  "redirect_url": "https://pay.example.com/TRX-20240215-093045-987654321098"
}

Note: redirect_url is present only for redirect requests.

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

Retrieving the QR Code File¶

This method allows you to retrieve the QR code file by its identifier. It is used for QR code payments (payment_method = qr) when you need the file itself rather than base64 in the response body.

Request¶

GET example.com/api/merchant/"merchant"/qr_file/"qr_file_id"

Important information

The URL structure above is an example. The ready-to-use URL is provided in the qr_file_url field — when creating a request, when requesting the request status, and in callback notifications. We recommend using it instead of building the URL yourself.

Headers¶

Name	Value
Content-Type*	application/json
X-Api-Key*	X-Api-Key

Response Headers¶

Name	Description
Content-Type	File MIME type (for example, image/png)
Content-Disposition	File name (RFC 5987 format for Unicode support)

Response Parameters¶

The method returns the binary data of the QR code file. The file format is determined by the Content-Type header.

Response Example¶

200Error 400 and other 4xx

Headers:

Content-Type: image/png
Content-Disposition: inline; filename="qr.png"; filename*=UTF-8''qr.png

Response body:

Binary file data

{
  "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, qr)	Payment type (card, SBP, bank account, IBAN, QR code)
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)
qr_file_id	int		QR code file identifier (only provided when payment_method = qr)
qr_file_url	string max: 512		Ready-to-use URL for retrieving the QR code file (only provided when payment_method = qr)
full_name	string		Recipient full name
bank_name*	string		Recipient bank name
redirect*	boolean		Redirect request indicator
redirect_url	string max: 512		Link to the payment page (only for redirect requests)

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 the payment details field matching the payment method is provided (number_card, phone_number, number_score, iban_number, qr_file_id + qr_file_url).

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"
}