Россия (QR СБП)
Выплаты оплатой динамического QR-кода СБП, выставленного получателем
Перед тем как начать
Авторизация
Как подписывать запросы API-токеном.
Обзор выплат
Общий формат запроса, поля ответа и статусы.
Это направление выплат доступно не всем мерчантам. Уточните доступность у вашего менеджера и убедитесь, что на вашем балансе мерчанта достаточно средств, прежде чем создавать выплату.
Обзор
| Валюта | Направление | Тип платежа |
|---|---|---|
RUB | Динамический QR-код СБП (платёжная ссылка НСПК) | SBP_QR |
Получатель — магазин, сервис или человек, принимающий оплату по СБП, — выставляет динамический QR-код СБП на сумму выплаты. Вы передаёте его платёжную ссылку НСПК, и выплата выполняется оплатой этого QR-кода.
Выплата завершается только после того, как НСПК подтвердит операцию по QR-коду, а не по ответу банка, который его оплатил. Обычно подтверждение приходит через несколько секунд после оплаты.
Принимаются только динамические QR-коды (type=02 в ссылке): по статическому QR НСПК не показывает факт оплаты. Статический QR-код отклоняется с ошибкой 400 до создания выплаты.
Сумма выплаты amount должна совпадать с суммой в QR-коде. Если сумма есть в ссылке (параметр sum, в копейках), расхождение отклоняется с ошибкой 400 до создания выплаты; иначе сумма проверяется при оплате QR-кода, и при расхождении выплата завершится статусом FAILED.
Создание выплаты
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"
}
}'Передавайте ссылку ровно так, как она зашита в QR-код, со всеми параметрами.
Поля account
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
name | string | ✅ Да | Имя получателя |
requisites | string | ✅ Да | Реквизиты получателя: номер карты, номер телефона, PIX-ключ и т. д. в зависимости от paymentType |
userId | string | ✅ Да | ID пользователя в вашей системе |
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | ✅ Да | Название получателя, например магазина. Не проверяется, сохраняется для вашего учёта |
requisites | string | ✅ Да | Платёжная ссылка НСПК динамического QR-кода: https://qr.nspk.ru/<qrcId>?type=02&… |
Требования к QR-коду
- Один QR-код — одна выплата. Не создавайте вторую выплату по QR-коду, который уже оплачивается или оплачен.
- QR-код должен оставаться действительным до оплаты: выставляйте его со сроком жизни хотя бы несколько минут. Если QR-код истёк или НСПК перестал его принимать (уже оплачен, отменён), выплата завершится статусом
EXPIRED. - Пока выплата в работе, QR-код не должен оплачивать никто другой.
Ошибки валидации
Запрос с некорректными реквизитами отклоняется с ошибкой 400 до создания выплаты и холда баланса:
| Причина | Что исправить |
|---|---|
Значение — не ссылка НСПК https://qr.nspk.ru/<qrcId> | account.requisites |
Статический QR-код (type=01) | account.requisites |
amount не совпадает с sum ссылки | amount |
Статусы
| Статус | Что означает для выплаты по QR СБП |
|---|---|
PROCESSING | QR-код принят и ждёт оплаты, либо оплата подтверждается в НСПК |
COMPLETED | НСПК подтвердил операцию по QR-коду |
FAILED | QR-код не удалось оплатить или НСПК не подтвердил оплату. Причина — в statusMessage |
EXPIRED | QR-код истёк или НСПК перестал его принимать до оплаты |
При FAILED и EXPIRED захолдированная сумма возвращается на баланс.
Ответ
В ответе возвращается стандартный объект выплаты со статусом CREATED. Сохраните id, чтобы отслеживать выплату.