QR-платежи

Для каждого заказа создаётся отдельный QR с суммой и сроком действия. NUMUS определяет партнёра по подписи. Если активна одна платёжная точка, её идентификатор в запросе не требуется.

Создать QR

POST https://api.numus.online/api/qr

Метод требует подпись Ed25519 и уникальный Idempotency-Key длиной 16–128 символов. Для сетевого повтора отправьте тот же ключ и то же тело.

POST /api/qr HTTP/1.1
Host: api.numus.online
Authorization: {"partnerID":"partner-001","key":"ssh-ed25519 ...","sign":"...","timestamp":"1784912400","nonce":"..."}
Content-Type: application/json
Idempotency-Key: order-2026-00000001

{
  "qrtype": "QRDynamic",
  "amount": 1490.50,
  "currency": "RUB",
  "qrDescription": "Заказ 100500",
  "customerID": "customer-42",
  "returnUrl": "https://merchant.example/orders/100500/payment-result"
}

Поля

Поле	Что передавать
`paymentPointID`	Необязателен при одной активной точке. При нескольких выберите точку из `GET /api/integration/payment-points`.
`amount`	Сумма в рублях, не более двух знаков после точки.
`currency`	`RUB`.
`qrDescription`	Назначение платежа для истории. Это описание, а не идентификатор заказа.
`customerID`	Ваш стабильный идентификатор покупателя; поле необязательное.
`returnUrl`	Необязательный адрес для этого заказа. Разрешён другой path и query на сохранённом HTTPS-домене.

Ответ

Если QR уже готов, ответ содержит ссылку и PNG:

{
  "id": "0190c5ad-2f51-7b1d-9f2e-e0a01d8f9a21",
  "paymentPointID": "shop-001-main",
  "amount": 1490.5,
  "currency": "RUB",
  "status": "QR_READY",
  "nspkurl": "https://qr.example/...",
  "qrImage": "data:image/png;base64,...",
  "qrExpirationDate": "2026-07-24T17:20:00Z",
  "statusUrl": "/api/qr/0190c5ad-2f51-7b1d-9f2e-e0a01d8f9a21"
}

Динамический QR действует не более 20 минут с момента создания. Используйте точное значение qrExpirationDate из ответа и после этого времени создавайте новую попытку с новым Idempotency-Key.

При статусе SUBMITTED запрашивайте statusUrl примерно раз в секунду. Остановитесь после получения QR, конечного статуса или через 45 секунд.

Сохраните поле id рядом с идентификатором заказа в своей базе. В callback оно возвращается как data.orderId и используется для связи уведомления с созданным QR-платежом.

Статусы

Статус	Значение	Действие
`CREATED`	Запрос сохранён	Подождать
`SUBMITTED`	QR готовится	Запрашивать `statusUrl`
`QR_READY`	QR можно показать	Открыть ссылку или показать PNG
`PENDING`	Ожидается оплата	Ждать подписанное уведомление
`COMPLETED`	Платёж подтверждён	Обработать событие один раз
`REJECTED`, `FAILED`	Платёж не состоялся	Создать новый платёж
`EXPIRED`, `CANCELLED`	QR больше не действует	Создать новый платёж

История и дневные итоги

GET https://api.numus.online/api/payments/{paymentPointID}

Возвращает только платежи текущего партнёра. Запрос подписывается Ed25519.

GET https://api.numus.online/api/payment-totals/{paymentPointID}?date=2026-07-24

Дата трактуется по московскому времени.

Частые ошибки

Код	Причина	Что проверить
`400`	Неверное тело или сумма	Названия полей, RUB и допустимый диапазон
`401`	Подпись не прошла проверку	partnerID, ключ, время, nonce и canonical body hash
`404`	Торговая точка не найдена	`paymentPointID` и окружение
`409`	Ключ уже использован с другим телом	Не меняйте тело при повторе
`429`	Превышена частота	Сделайте паузу, сохранив тот же ключ
`202`	Результат создания уточняется	Проверяйте исходный `statusUrl`; не создавайте новый платёж
`503`	Маршрут временно недоступен	Повторите тот же запрос с тем же ключом