NOMA / DEVELOPERSMerchant dashboard ↗

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

  1. Top up your payQR deposit in USDT through NOMA.
  2. Get the QR methods available to your store: GET /v1/payouts/methods.
  3. Send the QR code, method and amount: POST /v1/payouts.
  4. NOMA fixes the rate and fee and reserves the total on the deposit.
  5. NOMA pays the QR code. The result comes as a payout.* webhook and through GET /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.

CodeMethodCountryCurrency
sbpSBP QRRussiaRUB

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"}
}
FieldTypeDescription
methodstringoptionalQR method from GET /v1/payouts/methods. Default sbp.
qr_payloadstringrequiredQR code content as scanned, 8–2048 characters.
amount_minorintegerrequiredAmount in minor units of the method currency; must match the QR code.
merchant_order_idstringoptionalYour order number, 1–128 characters. Returned in responses and webhooks; NOMA does not check it for uniqueness.
descriptionstringoptionalUp to 255 characters.
metadataobjectoptionalAny 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"
}
FieldDescription
currency, amount_minorPaid amount in the QR currency.
effective_rate_e6QR currency per 1 USDT × 1,000,000 after the spread.
usdt_amount_micro, fee_microDebit and fee in millionths of USDT.
rate_sourcemarket or manual.
failure_reasonnull, rejected_by_provider or cancelled_by_operator.

07 · Statuses

StatusPhaseMeaning
pendingprogressFunds reserved, not yet sent. Can be cancelled.
processingprogressSent for payment; waiting for the result.
needs_reviewprogressResult not confirmed automatically; NOMA checks it manually. The reserve stays blocked.
completedfinalPaid; the deposit is debited.
failedfinalNot paid; the reserve is returned.
cancelledfinalCancelled 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, ...}
}
EventWhen
payout.completedQR code paid.
payout.failedNot paid; reserve returned.
payout.cancelledCancelled; reserve returned.

Verification and deduplication: see Webhooks.

10 · Errors

HTTPerrorWhat to do
400invalid_request, invalid_amountFix the body.
400unsupported_methodUse a method from GET /v1/payouts/methods.
402deposit_not_funded, insufficient_fundingTop up the payQR deposit. Nothing was reserved.
403kyb_required, account_inactiveComplete KYB or contact NOMA.
403payouts_disabledQR Payment is not enabled for your account.
404not_foundOperation does not exist or belongs to another store.
409idempotency_conflict, not_cancellableKey reused with another body, or already sent.
503no_provider_availableNot available for this method or amount now.
503rate_unavailable, rate_stale, rate_suspectRate temporarily unavailable. Retry later with the same key.

11 · Go-live checklist

  • Methods are taken from GET /v1/payouts/methods.
  • amount_minor matches the QR code.
  • Each operation has its own stored Idempotency-Key; timeouts are retried with the same key.
  • processing and needs_review mean "not finished": do not pay the same QR code another way.
  • Webhooks are verified and deduplicated; the deposit is monitored with GET /v1/balances.