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.
Acquiring
Accept payments from your customers: bank transfers, cards, wallets, crypto.
QR Terminal
In-store payments by QR through a separate acceptance gateway.
QR Payment
Pay local QR codes from your payQR deposit.
Transfers
Send money to recipients from your payout deposit.
| Product | Direction | Funded from | Balance account | Webhook events |
|---|---|---|---|---|
| Acquiring | Customer → store | The customer | payin_* | payment.* |
| QR Terminal | Customer → store | The customer | terminal_* | payment.* |
| QR Payment | Store → QR code | payQR deposit | deposit_usdt | payout.* |
| Transfers | Store → recipient | payout deposit | payout_usdt | transfer.* |
The payQR deposit and the payout deposit are separate. Funds do not move between them automatically.
02 · Onboarding
- 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.
- Submit KYB details in the dashboard.
- Agree with NOMA on products, methods, fees and limits.
- In Integrations, create an API key and set your HTTPS webhook URL (port 443). The API secret and webhook secret are shown once.
- For QR Payment and Transfers, top up the deposit through your NOMA manager. Check it with
GET /v1/balances. - Test with small amounts, check webhooks and reconciliation, then go live.
03 · API basics
| Base URL | https://api.nomapay.io |
|---|---|
| Format | JSON over HTTPS. Send Content-Type: application/json with a body. |
| Amounts | Integers 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. |
| Rates | Fields ending with _e6 are multiplied by 1,000,000: 79200000 = 79.2. |
| Time | ISO 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. |
| IDs | UUID strings issued by NOMA. |
| Reference | API reference, OpenAPI JSON. |
| Version | 1.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.
| HTTP | error | Meaning |
|---|---|---|
| 401 | missing_headers | One of the three headers is missing. |
| 401 | invalid_api_key | Unknown or revoked key. |
| 401 | invalid_signature | Signature mismatch or timestamp outside the window. |
| 403 | partner_suspended | The store is suspended. |
| 403 | ip_not_allowed | Source IP is not in your allowlist. |
| 429 | rate_limit_exceeded | Too 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
- Verify the signature over the raw body before parsing JSON. Check the timestamp (±5 minutes).
- Deduplicate by event
id. - Match the operation ID, currency and amounts to your records.
- Return HTTP 2xx after saving the event. Do slow work asynchronously.
| Product | Events | data |
|---|---|---|
| Acquiring | payment.paid, payment.paid_late, payment.expired, payment.cancelled | Payment object |
| QR Payment | payout.completed, payout.failed, payout.cancelled | QR Payment object |
| Transfers | transfer.completed, transfer.failed, transfer.cancelled | Transfer 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}
]
}
| Account | Product | Meaning |
|---|---|---|
payin_* | Acquiring | Accepted funds after fees, one account per settlement currency. |
deposit_usdt | QR Payment | payQR deposit. |
payout_usdt | Transfers | payout 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.
| HTTP | Reason | Result |
|---|---|---|
| 400 | Invalid input or unavailable method. | Not executed. |
| 401 / 403 | Signature, key, clock, KYB or product not enabled. | Not executed. |
| 402 | Deposit is not enough. | Not executed, nothing reserved. |
| 404 | Operation not found or belongs to another store. | — |
| 409 | Idempotency or state conflict, debit limit exceeded. | Not executed. |
| 429 | Rate limit. Respect Retry-After. | Not executed. |
| 503 | Method, rate or service temporarily unavailable. | Not executed. Retry later with the same key. |
| timeout | No 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.