NOMA / DEVELOPERSMerchant dashboard ↗

MERCHANT INTEGRATION · API V1

Build with NOMA.

Technical details for integrating with NOMA: onboarding, request signing, idempotency, webhooks, balances and errors. These rules apply to all products.

01 · Products

Each product is a separate integration with its own endpoints, statuses and webhooks. NOMA enables products for your account separately.

ProductDirectionFunded fromBalance accountWebhook events
AcquiringCustomer → storeThe customerpayin_*payment.*
QR TerminalCustomer → storeThe customerterminal_*payment.*
QR PaymentStore → QR codepayQR depositdeposit_usdtpayout.*
TransfersStore → recipientpayout depositpayout_usdttransfer.*

The payQR deposit and the payout deposit are separate. Funds do not move between them automatically.

02 · Onboarding

  1. Get an invitation link from your NOMA manager or from the partner who invited you, register with it and verify your email. Registration without an invitation is not available; contact info@nomapay.io.
  2. Submit KYB details in the dashboard.
  3. Agree with NOMA on products, methods, fees and limits.
  4. In Integrations, create an API key and set your HTTPS webhook URL (port 443). The API secret and webhook secret are shown once.
  5. For QR Payment and Transfers, top up the deposit through your NOMA manager. Check it with GET /v1/balances.
  6. Test with small amounts, check webhooks and reconciliation, then go live.

03 · API basics

Base URLhttps://api.nomapay.io
FormatJSON over HTTPS. Send Content-Type: application/json with a body.
AmountsIntegers in minor units of the currency: 150050 RUB = 1,500.50 RUB; 10000 CNY = 100.00 CNY; USDT in millionths (1000000 = 1 USDT). Field names end with _minor or _micro.
RatesFields ending with _e6 are multiplied by 1,000,000: 79200000 = 79.2.
TimeISO 8601, UTC: 2026-11-09T12:00:00+00:00 in API responses, 2026-11-09T12:00:00Z in webhook envelopes. Parse both as ISO 8601.
IDsUUID strings issued by NOMA.
ReferenceAPI reference, OpenAPI JSON.
Version1.0.1. New in 1.0.1: the buyer's phone customer_phone and the requires_customer_phone flag in Acquiring and QR Terminal. The change is backward compatible.

Client certificates are not required. Call the API only from your server; do not put the API secret into a browser or mobile app.

04 · Authentication

Send these headers on every /v1/* request:

x-api-key: YOUR_API_KEY
x-timestamp: UNIX_TIMESTAMP_MILLISECONDS
x-signature: LOWERCASE_HEX_HMAC_SHA256
body_hash = SHA256(raw_request_body).hexdigest()
message = METHOD_UPPERCASE + PATH_WITHOUT_QUERY + timestamp + body_hash
signature = HMAC_SHA256(api_secret, message).hexdigest()

No separators between the four parts. Sign the exact bytes you send; for GET and empty POST use an empty body. The path excludes the query string: for GET /v1/transfers?limit=10 sign /v1/transfers. Timestamp window: ±5 minutes.

HTTPerrorMeaning
401missing_headersOne of the three headers is missing.
401invalid_api_keyUnknown or revoked key.
401invalid_signatureSignature mismatch or timestamp outside the window.
403partner_suspendedThe store is suspended.
403ip_not_allowedSource IP is not in your allowlist.
429rate_limit_exceededToo many requests; wait for Retry-After seconds.
import hashlib, hmac, time

def signed_headers(api_key, api_secret, method, path, body=b""):
    ts = str(int(time.time() * 1000))
    message = method + path + ts + hashlib.sha256(body).hexdigest()
    signature = hmac.new(api_secret.encode(), message.encode(), hashlib.sha256)
    return {"x-api-key": api_key, "x-timestamp": ts,
            "x-signature": signature.hexdigest()}

Full example with webhook verification: nomapay_client.py.

05 · Idempotency

Creating requests (POST /v1/payments, POST /v1/payouts, POST /v1/transfers) require the Idempotency-Key header, 1–128 characters.

  • Store one key per operation before sending the request.
  • A retry uses the same key and body with a new timestamp and signature, and returns the original operation.
  • The same key with a different body returns 409 idempotency_conflict.
  • Keys are scoped to your store.

If a creating request times out, retry with the same key or look the operation up. Do not create a new attempt with a new key: the first request may have succeeded.

06 · Webhooks

NOMA sends JSON to the webhook URL of the API key that created the operation.

POST https://your-store.example/webhooks/noma
X-Gateway-Signature: t=UNIX_SECONDS,v1=HEX_SIGNATURE

{
  "id": "EVENT_ID",
  "type": "payment.paid",
  "created_at": "2026-11-09T12:03:00+00:00",
  "data": { ... operation object ... }
}
expected = HMAC_SHA256(webhook_secret, timestamp_seconds + "." + raw_body)
compare expected.hexdigest() to v1 using a constant-time comparison
  1. Verify the signature over the raw body before parsing JSON. Check the timestamp (±5 minutes).
  2. Deduplicate by event id.
  3. Match the operation ID, currency and amounts to your records.
  4. Return HTTP 2xx after saving the event. Do slow work asynchronously.
ProductEventsdata
Acquiringpayment.paid, payment.paid_late, payment.expired, payment.cancelledPayment object
QR Paymentpayout.completed, payout.failed, payout.cancelledQR Payment object
Transferstransfer.completed, transfer.failed, transfer.cancelledTransfer object

Delivery is at least once, up to 10 attempts over about 4 hours. Order is not guaranteed; use the API status to resolve conflicts. After rotating an API key, keep the old webhook handler and secret for existing operations.

07 · Event feed and balances

GET /v1/events?after=0&limit=50
GET /v1/balances

The event feed returns {"events": [...], "next_after": 123} with the same events as webhooks: each item has seq, id, type, created_at and data. limit is 1–100. Save next_after after processing a batch. Use it to catch up after downtime.

{
  "balances": [
    {"account": "payin_rub",    "currency": "RUB",  "amount_minor": 150050},
    {"account": "payin_usdt",   "currency": "USDT", "amount_minor": 0},
    {"account": "deposit_usdt", "currency": "USDT", "amount_minor": 25000000},
    {"account": "payout_usdt",  "currency": "USDT", "amount_minor": 40000000},
    {"account": "terminal_rub", "currency": "RUB",  "amount_minor": 0},
    {"account": "terminal_usdt", "currency": "USDT", "amount_minor": 0}
  ]
}
AccountProductMeaning
payin_*AcquiringAccepted funds after fees, one account per settlement currency.
deposit_usdtQR PaymentpayQR deposit.
payout_usdtTransferspayout deposit.

Amounts reserved for operations in progress are already deducted.

08 · Errors and retries

{"error": "idempotency_conflict", "message": "Idempotency-Key already used with a different request body"}

error is a stable code; message is for people and can change.

HTTPReasonResult
400Invalid input or unavailable method.Not executed.
401 / 403Signature, key, clock, KYB or product not enabled.Not executed.
402Deposit is not enough.Not executed, nothing reserved.
404Operation not found or belongs to another store.—
409Idempotency or state conflict, debit limit exceeded.Not executed.
429Rate limit. Respect Retry-After.Not executed.
503Method, rate or service temporarily unavailable.Not executed. Retry later with the same key.
timeoutNo response.Unknown. Retry with the same key or look the operation up.

09 · Security checklist

  • Keep the API secret and webhook secret on the server, out of source control and logs.
  • Verify every webhook signature and timestamp.
  • Use an idempotency key for every creating request.
  • Reconcile with status requests or the event feed, not only webhooks.
  • Rotate keys in the dashboard if a secret may have leaked.