Создание котировки (Prepare Order)

Первый шаг для оплаты QR-кода СБП — создание котировки с фиксированным курсом.

Endpoint

POST /orders/prepare

Параметры запроса

Параметр	Тип	Обязательный	Описание
`qrCode`	string	Да	QR СБП (URL/payload), строка `ST00012` (ЖКХ) или `gibdd:uin:{УИН}` (штраф ГИБДД), до 4000 символов
`externalOrderId`	string	Нет	Ваш внутренний ID заказа, до 255 символов. Вернётся в ордере, по нему работает поиск

Нужно право orders.create.

Пример запроса

curl -X POST 'https://b2b.lumowallet.io/orders/prepare' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "qrCode": "https://qr.nspk.ru/AS10003P3RCT8NTGH6LR6D3P815L3SHK?type=02&bank=100000000001&sum=50000&cur=RUB&crc=F4AB",
    "externalOrderId": "order-12345"
  }'

Пример ответа

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amountRub": 5000.00,
  "amountUsdt": 52.63,
  "rate": 95.00,
  "paymentType": "nspk",
  "expiresAt": "2026-03-10T12:00:30Z",
  "isBalanceSufficient": true,
  "merchantName": "ООО Кофейня"
}

Поля ответа

Поле	Тип	Описание
`id`	uuid	ID котировки — передайте его в accept. Ордер, созданный из котировки, получит тот же `id`
`amountRub`	number	Сумма в рублях
`amountUsdt`	number	Сумма в USDT по текущему курсу
`rate`	number	Курс RUB/USDT
`paymentType`	string	Тип платежа: `nspk`, `st00012` (ЖКХ) или `gibdd_uin` (штраф ГИБДД по реквизитам)
`expiresAt`	datetime	Время истечения котировки
`isBalanceSufficient`	boolean	Достаточно ли средств на балансе
`merchantName`	string	Название получателя (если доступно)

TTL котировки

Котировка действует 30 секунд. После истечения:

Котировка становится недействительной
Попытка accept вернёт 400 QUOTE_EXPIRED
Необходимо создать новую котировку

Проверка баланса

Поле isBalanceSufficient показывает, достаточно ли средств для оплаты:

true — можно вызывать accept
false — сначала пополните баланс

Что можно передать в `qrCode`

Одно поле принимает три типа платежа — тип определяется автоматически и возвращается в paymentType:

QR СБП/NSPK (paymentType: nspk) — ссылка qr.nspk.ru, диплинк банка либо ссылка multiqr.ru / platiqr.ru:

https://qr.nspk.ru/AS10003P3RCT8NTGH6LR6D3P815L3SHK?type=02&bank=100000000001&sum=50000&cur=RUB&crc=F4AB

ЖКХ — строка ST00012 (paymentType: st00012), сумма берётся из поля Sum:

ST00012|Name=ООО УК Комфорт|PersonalAcc=40702810...|Sum=350075|Purpose=Оплата ЖКУ

Штраф ГИБДД по УИН, сумма и реквизиты подтягиваются автоматически:

gibdd:uin:18810177230000000000

Штраф оплачивается одним из двух способов, и ваш код должен принимать оба: либо как обычный платёж СБП (paymentType: nspk, в merchantName — получатель из НСПК), либо по реквизитам (paymentType: gibdd_uin, merchantName: ГИБДД).

Подробности и реквизиты получателя — в гайде Оплата ЖКХ и штрафов ГИБДД.

Курс и комиссия

rate — это итоговый курс RUB/USDT с уже учтённой комиссией компании (qrRateOffsetBps). По нему рассчитан amountUsdt в этой котировке — именно эта сумма будет списана с баланса при accept. Сырой курс Rapira без комиссии и текущие лимиты на сумму можно посмотреть через GET /rates/current.

Лимиты по сумме

Каждой компании можно задать qrMinAmountRub / qrMaxAmountRub. По умолчанию: 0 ₽ ... 1 000 000 ₽. Если сумма QR не попадает в диапазон — endpoint вернёт 400 AMOUNT_BELOW_MIN / 400 AMOUNT_ABOVE_MAX, а границу и сумму QR — в details. Текущие лимиты отдаёт GET /rates/current. Изменение лимитов делается через техподдержку.

Ошибки

HTTP	`errorCode`	Описание
400	`VALIDATION_ERROR`	Пустой или слишком длинный `qrCode` / `externalOrderId`
400	`QR_INVALID`	НСПК отклонил QR — истёк, уже оплачен или неизвестен. Код отказа — в `details.nspkCode`
400	`QR_RESOLVE_FAILED`	Не удалось получить данные платежа по QR
400	`QR_AMOUNT_MISSING`	Из QR не удалось получить сумму
400	`AMOUNT_BELOW_MIN`	Сумма меньше `qrMinAmountRub`
400	`AMOUNT_ABOVE_MAX`	Сумма больше `qrMaxAmountRub`
400	`ST00012_SUM_MISSING` / `ST00012_SUM_INVALID`	В строке ЖКХ нет суммы или она некорректна
400	`GIBDD_UIN_INVALID`	УИН — не 20–25 цифр
400	`FINE_NOT_FOUND` / `FINE_ALREADY_PAID`	Штраф ГИБДД не найден / уже оплачен
401	`AUTH_REQUIRED` / `INVALID_API_KEY`	Нет ключа или ключ неверный
403	`PERMISSION_DENIED`	У ключа нет права `orders.create`
503	`RATE_UNAVAILABLE`	Курс временно недоступен, повторите через несколько секунд
503	`DRIVER_HELPER_TRANSIENT`	Сервис проверки штрафов недоступен, повторите позже. При сетевом сбое может прийти `500`

Если данные платежа получить не удалось — в том числе когда НСПК отклонил QR, — но в ссылке есть сумма (параметр sum в копейках или amount в рублях), котировка всё равно создаётся по этой сумме, без merchantName. Поэтому QR_INVALID и QR_RESOLVE_FAILED приходят только для ссылок без суммы.

Что дальше?

После получения котировки с isBalanceSufficient: true, переходите к подтверждению оплаты.