Russia (SBP QR)
Payouts by paying a dynamic SBP QR code issued by the recipient
Before you start
Authorization
How to sign your requests with the API token.
Payouts overview
Common request format, response fields and statuses.
This payout destination is not enabled for all merchants. Check availability with your manager, and make sure your merchant balance is sufficient before creating a payout.
Overview
| Currency | Destination | Payment type |
|---|---|---|
RUB | Dynamic SBP QR code (NSPK payment link) | SBP_QR |
The recipient — a store, a service or a person accepting payments via SBP — issues a dynamic SBP QR code for the payout amount. You pass its NSPK payment link, and the payout is made by paying this QR code.
The payout is completed only after NSPK confirms the operation on the QR code, not on the word of the paying bank. Confirmation usually takes a few seconds after the payment.
Only dynamic QR codes are accepted (type=02 in the link): for a static QR code NSPK does not show the fact of payment. A static QR code is rejected with 400 before the payout is created.
The payout amount must be equal to the amount in the QR code. If the link carries the amount (sum parameter, in kopecks), a mismatch is rejected with 400 before the payout is created; otherwise the amount is checked when the QR code is paid, and a mismatch ends the payout as FAILED.
Create the payout
POST /v1/payoutscurl -X POST "https://api.riopay.online/v1/payouts" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"amount": 1500,
"currency": "RUB",
"paymentType": "SBP_QR",
"serviceId": 123,
"externalId": "payout-123",
"account": {
"name": "ООО Ромашка",
"requisites": "https://qr.nspk.ru/AD10006M8KH8PJ5D9ROP3BNJ5DJ0GC4I?type=02&bank=100000000004&sum=150000&cur=RUB&crc=AB12",
"userId": "user_12345"
}
}'Pass the link exactly as it is encoded in the QR code, with all query parameters.
account fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✅ Yes | Recipient name |
requisites | string | ✅ Yes | Recipient requisites: card number, phone number, PIX key, etc., depending on paymentType |
userId | string | ✅ Yes | User ID in your system |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✅ Yes | Recipient name, for example the store name. Not checked, kept for your records |
requisites | string | ✅ Yes | NSPK payment link of the dynamic QR code: https://qr.nspk.ru/<qrcId>?type=02&… |
QR code requirements
- One QR code — one payout. Do not create a second payout for a QR code that is already being paid or has been paid.
- The QR code must stay valid until it is paid: issue it with a lifetime of at least several minutes. A QR code that expires or that NSPK stops accepting (already paid, canceled) ends the payout as
EXPIRED. - Nobody else must pay the QR code while the payout is in progress.
Validation errors
A request with invalid details is rejected with 400 before the payout is created and the balance is held:
| Reason | Field to fix |
|---|---|
The value is not an NSPK link https://qr.nspk.ru/<qrcId> | account.requisites |
Static QR code (type=01) | account.requisites |
amount differs from the sum of the link | amount |
Statuses
| Status | What it means for an SBP QR payout |
|---|---|
PROCESSING | The QR code is accepted and waiting to be paid, or the payment is being confirmed by NSPK |
COMPLETED | NSPK confirmed the operation on the QR code |
FAILED | The QR code could not be paid, or NSPK did not confirm the payment. The reason is in statusMessage |
EXPIRED | The QR code expired or NSPK stopped accepting it before it was paid |
FAILED and EXPIRED release the held amount back to your balance.
Response
The response is a standard payout object with the CREATED status. Store the id to track the payout.