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
- Get the methods available to your store:
GET /v1/payments/methods. - Create a payment with one of them:
POST /v1/payments. - Send the customer to the NOMA checkout page or use the payment data in your own checkout.
- NOMA sends
payment.paidto your webhook. You can also checkGET /v1/payments/{id}. - 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.
| Code | Method | Type | Currency |
|---|---|---|---|
sbp | SBP (Faster Payments System) | Bank transfer | RUB |
mir | MIR card | Card | RUB |
visa | Visa | Card | Per account |
mastercard | Mastercard | Card | Per account |
apple_pay | Apple Pay | Wallet | Per account |
google_pay | Google Pay | Wallet | Per account |
usdt_trc | USDT (TRC20) | Crypto | USDT |
usdt_bsc | USDT (BSC) | Crypto | USDT |
btc | Bitcoin | Crypto | BTC |
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
}
]
}
| Field | Description |
|---|---|
method | Code for POST /v1/payments. |
currency | Currency of the payment amount and of the balance it goes to. |
min_amount_minor, max_amount_minor | Limits per payment in minor units, or null. |
requires_customer_email | Send customer_email when true. |
requires_customer_phone | Send 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"
}
| Field | Type | Description | |
|---|---|---|---|
method | string | required | Method code from GET /v1/payments/methods. |
amount_minor | integer | required | Amount in minor units of the method currency. In the example: 150050 kopecks = 1,500.50 RUB. |
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. |
customer_email | string | optional | Buyer's email. Required when the method has requires_customer_email: true. |
customer_phone | string | optional | Buyer'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: sendcustomer_phone, for example+79001234567.requires_customer_email: true: sendcustomer_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"
}
| Field | Description |
|---|---|
id | Payment ID. |
product | acquiring here; terminal for QR Terminal payments. |
public_token | Token of the NOMA checkout page /pay/{public_token}. |
currency, amount_minor | Requested amount in the method currency. |
amount_received_minor | Amount actually paid, after confirmation. |
fee_minor | NOMA fee, after confirmation. |
qr_payload | QR data, for methods paid by QR. Can be null at first and may change. |
payment_link | Link that opens the payment. Can be null at first. |
expires_at | Payment 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
| Status | Phase | Meaning |
|---|---|---|
pending | progress | Waiting for payment. Do not fulfill the order. |
paid | final | Payment confirmed. |
paid_late | final | Payment confirmed after the deadline. Apply your late-payment policy. |
expired | final* | Deadline passed without payment. *Can still change to paid_late. |
cancelled | final | Payment 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, ...}
}
| Event | When |
|---|---|
payment.paid | Payment confirmed. |
payment.paid_late | Payment confirmed after the deadline. |
payment.expired | Deadline passed. |
payment.cancelled | Payment 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
- In the dashboard, open Acquiring → Balance and send a withdrawal request with your details. Available after KYB approval when the balance is positive.
- NOMA contacts you to agree the amount and details.
- 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
| HTTP | error | What to do |
|---|---|---|
| 400 | invalid_request, invalid_amount | Fix the body. |
| 400 | method_not_available | Use a method from GET /v1/payments/methods. |
| 400 | customer_email_required, invalid_customer_email | Send the buyer's email. |
| 400 | customer_phone_required | Send the buyer's phone in customer_phone. A phone that is not in international format (+79001234567) fails with invalid_request. |
| 400 | idempotency_key_required, invalid_idempotency_key | Send a 1–128 character key. |
| 403 | kyb_required | Complete KYB. |
| 403 | payins_disabled | Acquiring is not enabled for your account. |
| 404 | not_found | Payment does not exist or belongs to another store. |
| 409 | idempotency_conflict | The key was used with another body. |
| 409 | request_in_progress | A request with this key is still being processed. Retry in a few seconds with the same key and body. |
| 503 | no_provider_available | The method or amount is not available now. Check limits or contact NOMA. |
| 503 | upstream_unavailable | Temporary. 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_phoneorrequires_customer_email. - Payments are created only on your server.
- Each payment attempt has its own stored Idempotency-Key.
- Webhook signature, timestamp and event
iddeduplication are implemented. - Orders are fulfilled only on
paidorpaid_late, matched by ID, currency and amount. - Pending payments are reconciled with
GET /v1/payments/{id}or the event feed.