NOMA / DEVELOPERSMerchant dashboard ↗

ACQUIRING · PAYIN

Acquiring

Accepting payments from your customers. Create a payment on your server, send the customer to checkout, and get the result by webhook or API.

01 · How it works

  1. Get the methods available to your store: GET /v1/payments/methods.
  2. Create a payment with one of them: POST /v1/payments.
  3. Send the customer to the NOMA checkout page or use the payment data in your own checkout.
  4. NOMA sends payment.paid to your webhook. You can also check GET /v1/payments/{id}.
  5. The amount minus the fee goes to your acquiring balance in the payment currency. You withdraw it on request.

Requests are signed with x-api-key, x-timestamp and x-signature; POST also needs Idempotency-Key. See Authentication.

02 · Payment methods

NOMA supports several methods. Each store gets its own set: the list depends on your account and agreement with NOMA.

CodeMethodTypeCurrency
sbpSBP (Faster Payments System)Bank transferRUB
mirMIR cardCardRUB
visaVisaCardPer account
mastercardMastercardCardPer account
apple_payApple PayWalletPer account
google_payGoogle PayWalletPer account
usdt_trcUSDT (TRC20)CryptoUSDT
usdt_bscUSDT (BSC)CryptoUSDT
btcBitcoinCryptoBTC

Not every method is available now. Use the API to get the methods you can use:

GET /v1/payments/methods

Response · HTTP 200

{
  "methods": [
    {
      "method": "sbp",
      "name": "SBP",
      "currency": "RUB",
      "min_amount_minor": 50000,
      "max_amount_minor": null,
      "requires_customer_email": false,
      "requires_customer_phone": true
    }
  ]
}
FieldDescription
methodCode for POST /v1/payments.
currencyCurrency of the payment amount and of the balance it goes to.
min_amount_minor, max_amount_minorLimits per payment in minor units, or null.
requires_customer_emailSend customer_email when true.
requires_customer_phoneSend customer_phone when true. Since API 1.0.1.

The list includes only methods enabled for your store and for the currencies you accept (set in the dashboard). An empty list means no method is available yet; contact NOMA.

03 · Create a payment

POST /v1/payments
Content-Type: application/json
Idempotency-Key: order-1042-payment-1

{
  "method": "sbp",
  "amount_minor": 150050,
  "merchant_order_id": "1042",
  "description": "Order 1042",
  "metadata": {"order_id": "1042"},
  "customer_phone": "+79001234567"
}
FieldTypeDescription
methodstringrequiredMethod code from GET /v1/payments/methods.
amount_minorintegerrequiredAmount in minor units of the method currency. In the example: 150050 kopecks = 1,500.50 RUB.
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.
customer_emailstringoptionalBuyer's email. Required when the method has requires_customer_email: true.
customer_phonestringoptionalBuyer's phone in international format: +, country code and number, 7–15 digits, no spaces (+79001234567). Required when the method has requires_customer_phone: true. Since API 1.0.1.

The amount is not converted: send it in the currency of the method.

Buyer's phone and email

Some payment methods work only when the provider receives the buyer's phone or email. GET /v1/payments/methods shows what each method needs:

  • requires_customer_phone: true: send customer_phone, for example +79001234567.
  • requires_customer_email: true: send customer_email.

A method can need both. Ask the buyer for this data in your checkout before you create the payment. Without it the request fails with customer_phone_required or customer_email_required, and no payment is created.

NOMA passes the phone and email only to a provider that requires them. They are not returned in the payment object or in webhooks. The requirement can change, so read the flags from the methods list instead of hard-coding them. On the NOMA dashboard and storefront the buyer is asked for this data automatically.

04 · Payment object

Response · HTTP 201

{
  "id": "PAYMENT_ID",
  "product": "acquiring",
  "public_token": "PUBLIC_CHECKOUT_TOKEN",
  "method": "sbp",
  "status": "pending",
  "currency": "RUB",
  "amount_minor": 150050,
  "amount_received_minor": null,
  "fee_minor": null,
  "merchant_order_id": "1042",
  "description": "Order 1042",
  "metadata": {"order_id": "1042"},
  "qr_payload": "https://qr.nspk.ru/...",
  "payment_link": "https://...",
  "expires_at": "2026-11-09T12:15:00+00:00",
  "paid_at": null,
  "created_at": "2026-11-09T12:00:00+00:00"
}
FieldDescription
idPayment ID.
productacquiring here; terminal for QR Terminal payments.
public_tokenToken of the NOMA checkout page /pay/{public_token}.
currency, amount_minorRequested amount in the method currency.
amount_received_minorAmount actually paid, after confirmation.
fee_minorNOMA fee, after confirmation.
qr_payloadQR data, for methods paid by QR. Can be null at first and may change.
payment_linkLink that opens the payment. Can be null at first.
expires_atPayment deadline.

05 · Checkout

NOMA checkout (recommended). Redirect the customer to https://nomapay.io/pay/{public_token}. The page shows what the method needs (QR code, payment button) and the current status.

Your own checkout. Show qr_payload as a QR code and/or payment_link as a button. Get fresh data with GET /v1/payments/{id} instead of caching it. A redirect back to your site does not confirm payment; wait for the status.

06 · Statuses

StatusPhaseMeaning
pendingprogressWaiting for payment. Do not fulfill the order.
paidfinalPayment confirmed.
paid_latefinalPayment confirmed after the deadline. Apply your late-payment policy.
expiredfinal*Deadline passed without payment. *Can still change to paid_late.
cancelledfinalPayment cancelled.

07 · Confirm payment

GET /v1/payments/{id}

Returns the payment object. Check the ID, currency and amount against your order. Use webhooks as the main signal and this request for reconciliation; poll every 5–10 seconds at most.

08 · Webhooks

{
  "id": "EVENT_ID",
  "type": "payment.paid",
  "created_at": "2026-11-09T12:03:00Z",
  "data": {"id": "PAYMENT_ID", "status": "paid", "currency": "RUB",
           "amount_minor": 150050, "amount_received_minor": 150050, ...}
}
EventWhen
payment.paidPayment confirmed.
payment.paid_latePayment confirmed after the deadline.
payment.expiredDeadline passed.
payment.cancelledPayment cancelled.

Verify X-Gateway-Signature and deduplicate by event id: see Webhooks. Fulfill each order once.

09 · Balance and fees

GET /v1/balances

Confirmed payments go to the acquiring balance of the payment currency: payin_rub, payin_usdt and so on. The fee is a percentage agreed for your account, fixed in the payment when it is created: the balance grows by amount_received_minor − fee_minor.

10 · Withdraw your balance

  1. In the dashboard, open Acquiring → Balance and send a withdrawal request with your details. Available after KYB approval when the balance is positive.
  2. NOMA contacts you to agree the amount and details.
  3. After the transfer, NOMA records the withdrawal and the balance decreases.

Withdrawals are requested in the dashboard; there is no API endpoint for them.

11 · Errors

HTTPerrorWhat to do
400invalid_request, invalid_amountFix the body.
400method_not_availableUse a method from GET /v1/payments/methods.
400customer_email_required, invalid_customer_emailSend the buyer's email.
400customer_phone_requiredSend the buyer's phone in customer_phone. A phone that is not in international format (+79001234567) fails with invalid_request.
400idempotency_key_required, invalid_idempotency_keySend a 1–128 character key.
403kyb_requiredComplete KYB.
403payins_disabledAcquiring is not enabled for your account.
404not_foundPayment does not exist or belongs to another store.
409idempotency_conflictThe key was used with another body.
409request_in_progressA request with this key is still being processed. Retry in a few seconds with the same key and body.
503no_provider_availableThe method or amount is not available now. Check limits or contact NOMA.
503upstream_unavailableTemporary. Retry with the same key and body.

12 · Go-live checklist

  • Methods are taken from GET /v1/payments/methods, not hard-coded.
  • The buyer's phone and email are sent when the method has requires_customer_phone or requires_customer_email.
  • Payments are created only on your server.
  • Each payment attempt has its own stored Idempotency-Key.
  • Webhook signature, timestamp and event id deduplication are implemented.
  • Orders are fulfilled only on paid or paid_late, matched by ID, currency and amount.
  • Pending payments are reconciled with GET /v1/payments/{id} or the event feed.