Payout Requests¶

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

Creating a Payout Request¶

Request¶

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

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)	Payout type (card, SBP, bank account, IBAN)
fiat_amount*	string		Request amount in fiat currency with two decimal places
fiat_currency*	string	enum	Order currency. Available values are listed in the regions list
timeout	int		Payout timeout in minutes
number_score	string (20)		Bank account number (for bank account payouts)
number_card	string (16)		Card number (for card payouts)
phone_number	string min 11 max:13		Phone number (for SBP payouts)
iban_number	string max: 34		IBAN (for IBAN payouts)
bank_name	string max: 72		Recipient bank (required when payment_method = sbp)
bik	string		Recipient bank BIC (if available)
full_name	string max: 128		Recipient full name (if available)
success_callback_url*	string max: 512		URL for successful payout notification
error_callback_url*	string max: 512		URL for payout cancellation by the platform
customer	string max: 128		Customer identifier
order_description	string max: 8000		Order description
sign*	string		Request signature

Request Signature Generation Method:¶

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

order_id : fiat_amount : number_score/number_card/phone_number/iban_number : fiat_currency : sign_key

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

Signature generation example:

String to sign:

order123:1500.00:79161234567:rub:test_sign_key

SHA256 result:

53f49a84b929a1c6bf16fdf36ed151738def4b30a8088237ce480ffef538aa2f

Request Example¶

{
  "order_id": "order123",
  "payment_method": "sbp",
  "fiat_amount": "1500.00",
  "fiat_currency": "rub",
  "timeout": 30,
  "phone_number": "79161234567",
  "bank_name": "Sberbank",
  "bik": "044525225",
  "full_name": "Ivanov Ivan Ivanovich",
  "success_callback_url": "https://yourwebsite.com/success",
  "error_callback_url": "https://yourwebsite.com/error",
  "customer": "CUST12345",
  "order_description": "Reward payout for completed work",
  "sign": "53f49a84b929a1c6bf16fdf36ed151738def4b30a8088237ce480ffef538aa2f"
}

Response Parameters¶

Name	Type	Description
internal_transaction_id*	string max: 72	Unique transaction ID in the system (internal identifier, provided for informational purposes)
fiat_amount*	string	Transaction amount in fiat currency
usdt_amount*	string	Transaction amount in USDT
merchant_spent_usdt*	string	USDT amount debited from merchant balance (4 decimal places)
fiat_currency*	string	Fiat currency code
exchange_rate*	string	Fiat/USDT exchange rate (4 decimal places)
payment_method*	string	Payment method
reject_callback_url*	string max: 512	URL for payout cancellation by the merchant

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
low balance	Your balance is too low to create a request
this payment method is disabled for your merchant	This payout method is disabled for your merchant

Note: The error list is not exhaustive and provides only the main errors, please consider this during integration.

Response Example¶

200Error 400 and other 4xx

{
  "ok": true,
  "internal_transaction_id": "TRX-20240215-093045-123456789012",
  "fiat_amount": "1500.00",
  "usdt_amount": "15.8765",
  "merchant_spent_usdt": "15.2500",
  "fiat_currency": "rub",
  "exchange_rate": "98.2472",
  "payment_method": "sbp",
  "reject_callback_url": "https://yourwebsite.com/reject"
}

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

Payout 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_out)	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 spent by merchant
fiat_currency*	string		Fiat currency code
exchange_rate*	string		Exchange rate
payment_method*	string	enum (card, sbp, score, iban)	Payout 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
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. 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": "p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1",
  "type": "pay_out",
  "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": "Petrov Petr Petrovich",
  "bank_name": "Tinkoff"
}

Payout Request Status Inquiry¶

Request¶

GET example.com/api/merchant/"merchant"/status_pay_out/"pay_out_id"/

Headers¶

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

Response Parameters¶

Name	Type	Format	Description
order_id*	string max: 255		Request ID in your system
type*	string	enum (pay_out)	Operation type
status*	string	enum (expectation, successful, rejected_timeout, rejected_merchant, rejected_gate)	Request status (expectation - awaiting payout, 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 spent by merchant
fiat_currency*	string		Fiat currency code
exchange_rate*	string		Exchange rate
payment_method*	string	enum (card, sbp, score, iban)	Payout 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
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
cheque_urls	array		Array of receipt URLs (if available)

Note: 1. Only one of the payment details fields (number_card, phone_number, number_score, iban_number) is provided depending on the payment method. 2. The cheque_urls field is only provided if receipts are available for the request.

Important! Do not use polling to monitor request status. The platform server has rate limits on status requests. Use callback functionality to monitor request status. If you need to use polling, please coordinate this with the platform's technical support.

Response Example¶

200Error 400 and other 4xx

{
  "ok": true,
  "order_id": "123456789",
  "type": "pay_out",
  "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": "Petrov Petr Petrovich",
  "bank_name": "Tinkoff",
  "cheque_urls": [
    "https://yourwebsite.com/cheque1.pdf",
    "https://yourwebsite.com/cheque2.pdf",
    "https://yourwebsite.com/cheque3.pdf"
  ]
}

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

Payout Request Cancellation by Merchant¶

Request¶

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

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

Response Example¶

200Error 400 and other 4xx

{
  "ok": true
}

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