QR PAYMENT · PAYQR
QR Payment
Paying local QR codes from your payQR deposit. You send the QR code and the amount; NOMA pays it and debits the deposit in USDT at a rate fixed at creation.
01 · How it works
- Top up your payQR deposit in USDT through NOMA.
- Get the QR methods available to your store:
GET /v1/payouts/methods. - Send the QR code, method and amount:
POST /v1/payouts. - NOMA fixes the rate and fee and reserves the total on the deposit.
- NOMA pays the QR code. The result comes as a
payout.*webhook and throughGET /v1/payouts/{id}.
Requests are signed with x-api-key, x-timestamp and x-signature; POST also needs Idempotency-Key. See Authentication. Paths start with /v1/payouts for historical reasons.
02 · QR methods
A QR method is a local QR payment scheme of a country. Each method has its own currency.
| Code | Method | Country | Currency |
|---|---|---|---|
sbp | SBP QR | Russia | RUB |
More countries are added over time. Get the methods available to your store from the API:
GET /v1/payouts/methods
Response · HTTP 200
{
"methods": [
{
"method": "sbp",
"name": "SBP QR",
"country": "RU",
"currency": "RUB",
"min_amount_minor": null,
"max_amount_minor": null
}
]
}
An empty list means no QR method is enabled yet. 403 means QR Payment is not enabled for your account.
03 · Fund the payQR deposit
Top-ups are arranged with your NOMA manager. Check the balance with GET /v1/balances, account deposit_usdt (millionths of USDT). This deposit is used only for QR payments.
04 · Rate and fee
effective_rate = market rate (QR currency per USDT) × (1 − spread) usdt_amount = amount / effective_rate (rounded up to 0.000001 USDT) fee = usdt_amount × fee_percent debit = usdt_amount + fee
Spread and fee are agreed for your account and fixed in the operation. Example for sbp: 1,600.00 RUB at 79.2 RUB/USDT with a 2% fee gives usdt_amount_micro = 20,202,021 and fee_micro = 404,040, total 20.606061 USDT.
If the rate is missing or out of date, new payments are rejected with 503 rate_unavailable, rate_stale or rate_suspect.
05 · Pay a QR code
POST /v1/payouts
Content-Type: application/json
Idempotency-Key: qr-2091
{
"method": "sbp",
"qr_payload": "https://qr.nspk.ru/AD10006...?type=02&sum=160000&cur=RUB",
"amount_minor": 160000,
"merchant_order_id": "INV-2091",
"description": "Supplier invoice 2091",
"metadata": {"invoice_id": "2091"}
}
| Field | Type | Description | |
|---|---|---|---|
method | string | optional | QR method from GET /v1/payouts/methods. Default sbp. |
qr_payload | string | required | QR code content as scanned, 8–2048 characters. |
amount_minor | integer | required | Amount in minor units of the method currency; must match the QR code. |
merchant_order_id | string | optional | Your order number, 1–128 characters. Returned in responses and webhooks; NOMA does not check it for uniqueness. |
description | string | optional | Up to 255 characters. |
metadata | object | optional | Any JSON object; returned unchanged. |
06 · QR Payment object
Response · HTTP 201
{
"id": "PAYQR_ID",
"status": "completed",
"qr_payload": "https://qr.nspk.ru/...",
"amount_minor": 160000,
"currency": "RUB",
"usdt_amount_micro": 20202021,
"fee_micro": 404040,
"effective_rate_e6": 79200000,
"rate_source": "market",
"failure_reason": null,
"merchant_order_id": "INV-2091",
"description": "Supplier invoice 2091",
"metadata": {"invoice_id": "2091"},
"completed_at": "2026-11-09T12:00:04+00:00",
"created_at": "2026-11-09T12:00:00+00:00"
}
| Field | Description |
|---|---|
currency, amount_minor | Paid amount in the QR currency. |
effective_rate_e6 | QR currency per 1 USDT × 1,000,000 after the spread. |
usdt_amount_micro, fee_micro | Debit and fee in millionths of USDT. |
rate_source | market or manual. |
failure_reason | null, rejected_by_provider or cancelled_by_operator. |
07 · Statuses
| Status | Phase | Meaning |
|---|---|---|
pending | progress | Funds reserved, not yet sent. Can be cancelled. |
processing | progress | Sent for payment; waiting for the result. |
needs_review | progress | Result not confirmed automatically; NOMA checks it manually. The reserve stays blocked. |
completed | final | Paid; the deposit is debited. |
failed | final | Not paid; the reserve is returned. |
cancelled | final | Cancelled before sending; the reserve is returned. |
An operation is never paid twice. If the result is unknown, it stays in processing or needs_review until confirmed.
08 · Get and cancel
GET /v1/payouts/{id}
POST /v1/payouts/{id}/cancel
Cancellation works only in pending; otherwise 409 not_cancellable. Send the cancel request with an empty body.
09 · Webhooks
{
"id": "EVENT_ID",
"type": "payout.completed",
"created_at": "2026-11-09T12:00:05Z",
"data": {"id": "PAYQR_ID", "status": "completed", "currency": "RUB",
"amount_minor": 160000, "usdt_amount_micro": 20202021, ...}
}
| Event | When |
|---|---|
payout.completed | QR code paid. |
payout.failed | Not paid; reserve returned. |
payout.cancelled | Cancelled; reserve returned. |
Verification and deduplication: see Webhooks.
10 · Errors
| HTTP | error | What to do |
|---|---|---|
| 400 | invalid_request, invalid_amount | Fix the body. |
| 400 | unsupported_method | Use a method from GET /v1/payouts/methods. |
| 402 | deposit_not_funded, insufficient_funding | Top up the payQR deposit. Nothing was reserved. |
| 403 | kyb_required, account_inactive | Complete KYB or contact NOMA. |
| 403 | payouts_disabled | QR Payment is not enabled for your account. |
| 404 | not_found | Operation does not exist or belongs to another store. |
| 409 | idempotency_conflict, not_cancellable | Key reused with another body, or already sent. |
| 503 | no_provider_available | Not available for this method or amount now. |
| 503 | rate_unavailable, rate_stale, rate_suspect | Rate temporarily unavailable. Retry later with the same key. |
11 · Go-live checklist
- Methods are taken from
GET /v1/payouts/methods. amount_minormatches the QR code.- Each operation has its own stored Idempotency-Key; timeouts are retried with the same key.
processingandneeds_reviewmean "not finished": do not pay the same QR code another way.- Webhooks are verified and deduplicated; the deposit is monitored with
GET /v1/balances.