Payment Docs
Payouts

Russia (SBP QR)

Payouts by paying a dynamic SBP QR code issued by the recipient

Before you start

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

CurrencyDestinationPayment type
RUBDynamic 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/payouts
curl -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

FieldTypeRequiredDescription
namestring✅ YesRecipient name
requisitesstring✅ YesRecipient requisites: card number, phone number, PIX key, etc., depending on paymentType
userIdstring✅ YesUser ID in your system
FieldTypeRequiredDescription
namestring✅ YesRecipient name, for example the store name. Not checked, kept for your records
requisitesstring✅ YesNSPK 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:

ReasonField 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 linkamount

Statuses

StatusWhat it means for an SBP QR payout
PROCESSINGThe QR code is accepted and waiting to be paid, or the payment is being confirmed by NSPK
COMPLETEDNSPK confirmed the operation on the QR code
FAILEDThe QR code could not be paid, or NSPK did not confirm the payment. The reason is in statusMessage
EXPIREDThe 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.

Payout object fields

Next steps

On this page