Быстрые откупы по QR

Быстрый откуп — выплата, у которой сумму задаёт не мерчант, а сам QR-код. Вы передаёте QR-ссылку, платформа проверяет её, извлекает сумму и создаёт обычную Pay-Out сделку с методом qr.

Сценарий рассчитан на случай, когда получатель предъявляет готовый QR к оплате: вам не нужно ни разбирать его самостоятельно, ни доверять сумме, которую назвал клиент.

Чем отличается от обычной выплаты

	Обычный Pay-Out	Быстрый откуп
Сумма	Передаёте вы, в поле `amount`	Читается из QR
Реквизиты	Передаёте вы	Содержатся в QR
Валюта	Валюта кабинета	Только `RUB`
Метод сделки	По реквизиту	Всегда `qr`
Дальнейшая обработка	Стандартная	Стандартная

Начиная со статуса pending быстрый откуп ничем не отличается от обычной выплаты: те же статусы, те же webhook-уведомления, тот же метод отмены.

Поддерживаемые QR

Принимаются ссылки только с четырёх доменов:

Домен	Откуда берётся сумма
`qr.nspk.ru`	Из данных QR по запросу в НСПК
`nspk.ru`	Из данных QR по запросу в НСПК
`multiqr.ru`	Из query-параметра `amount`
`platiqr.ru`	Из query-параметра `amount`

Для доменов НСПК источником истины служит ответ платёжной системы, а не то, что написано в query-параметрах ссылки.

Порядок вызовов

Шаг 1. Проверьте QR

POST /payment/instant-pay-out/validate HTTP/1.1
Host: https://svc.cashwell.io
Content-Type: application/json
X-Secure-Key: <ваш API-ключ>

{
  "qrCode": "https://qr.nspk.ru/AD10006BVTEURKJF91L9GOBEE69OVA5M"
}

{ "valid": true, "amount": 1293.34 }

Для непригодного QR ответ будет { "valid": false, "amount": null }. Причину отказа метод не раскрывает — это защита от перебора: по ответу нельзя понять, дело в домене, в самом QR или в его состоянии.

Шаг необязателен, но полезен: он позволяет показать сумму клиенту до списания средств.

Шаг 2. Создайте откуп

POST /payment/instant-pay-out HTTP/1.1
Host: https://svc.cashwell.io
Content-Type: application/json
X-Secure-Key: <ваш API-ключ>

{
  "qrCode": "https://qr.nspk.ru/AD10006BVTEURKJF91L9GOBEE69OVA5M",
  "merchantTransactionId": "buyout-3001",
  "callbackUrl": "https://example.com/callback",
  "ownerName": "Иван Иванов"
}

Поле	Обяз.	Описание
`qrCode`	да	QR-ссылка с поддерживаемого домена
`merchantTransactionId`	да	Ваш идентификатор операции
`callbackUrl`	нет	Адрес для webhook по этой сделке
`ownerName`	нет	Имя получателя, если оно вам известно
`payerInfo`	нет	Данные получателя в вашей системе

В ответ приходит обычная Pay-Out сделка. Дальше следите за ней через webhook-уведомления и стандартные методы получения сделок.

Запрещённые поля

Запрос будет отклонён с INVALID_PARAMS, если в теле присутствует любое из:

Поле	Почему нельзя
`amount`	Сумму задаёт QR. Передача поля означала бы попытку её подменить
`currency`, отличная от `RUB`	Сценарий работает только с рублями
`isMatching`, `matchingTransactionId`	Быстрые откупы не участвуют в matching

Когда создание не пройдёт

QR-ссылка невалидна или домен не поддерживается;
в QR нет суммы или она вне допустимых границ;
НСПК вернул неуспешный статус по этому QR;
передана валюта, отличная от RUB;
merchantTransactionId уже использован;
на балансе недостаточно средств.

Конкретные коды — в разделе Коды ошибок.

Время жизни

Быстрый откуп живёт заметно меньше обычной выплаты — около двух с половиной минут. Это осознанное ограничение: сумма и реквизит привязаны к конкретному QR, который может быть оплачен кем-то другим.

Если исполнитель не найден за это время, сделка отменяется, а средства возвращаются на баланс. Повторить попытку можно новым запросом с новым merchantTransactionId.

Что дальше

Проверить QR — полный контракт метода
Создать быстрый откуп — полный контракт метода
Выплаты (Pay-Out) — общая механика выплат
Статусы сделок — как читать статус созданной сделки