TRANSFERS · PAYOUT · API V1
Transfers
Sending money to recipients through local payment methods in different countries, paid from your payout deposit. This page covers available currencies and methods, creating and tracking transfers, statuses, webhooks and errors.
Overview
Transfers support several payment methods in different countries. Each method belongs to a currency, for example CNY · Alipay. The list depends on your account and changes over time: read it from GET /v1/transfers/currencies.
| Currency | Method | Recipient |
|---|---|---|
| CNY · Chinese yuan | alipay · Alipay | Alipay account |
- Top up your payout deposit in USDT.
- Get the available currencies and methods:
GET /v1/transfers/currencies. - Create a transfer with your own
external_id:POST /v1/transfers. NOMA fixes the rate and fee and reserves the total on the deposit. - Track the status with
transfer.*webhooks andGET /v1/transfers/{id}orGET /v1/transfers/by-external-id/{external_id}.
x-api-key, x-timestamp and x-signature; POST /v1/transfers also needs Idempotency-Key. See Getting started → Authentication.01 · System information
| API server | https://api.nomapay.io |
|---|---|
| Dashboard | nomapay.io/cabinet — API keys, webhook URL, operations. |
| Format | JSON over HTTPS. Amounts are integers in minor units of the currency; USDT in millionths. |
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/transfers/currencies | Available currencies and methods |
| POST | /v1/transfers | Create a transfer |
| GET | /v1/transfers/{id} | Get a transfer by NOMA ID |
| GET | /v1/transfers | List transfers |
| GET | /v1/transfers/by-external-id/{external_id} | Get a transfer by your number |
| POST | /v1/transfers/{id}/cancel | Cancel a transfer |
| GET | /v1/balances | Balances, including the payout deposit |
02 · Payout deposit
Transfers are paid from the payout deposit in USDT. Top-ups are arranged with your NOMA manager. Check the deposit with GET /v1/balances, account payout_usdt (millionths of USDT).
03 · Available currencies
GET /v1/transfers/currencies
Returns the currencies and methods your store can use right now. A method appears only when it is enabled for your account and ready to execute.
Response · HTTP 200
{
"currencies": [
{
"currency": "CNY",
"name": "Chinese yuan",
"minor_units": 2,
"methods": [
{
"method": "alipay",
"name": "Alipay",
"min_amount_minor": null,
"max_amount_minor": null,
"sla_minutes": 30,
"recipient_fields": [
{"name": "recipient_id", "description": "Alipay account ID: phone number or email", "required": true},
{"name": "recipient_name", "description": "Recipient name as registered in Alipay", "required": true}
]
}
]
}
]
}
| Field | Description |
|---|---|
currency | ISO 4217 code: use it in POST /v1/transfers. |
minor_units | Decimal places: 2 means amount_minor = 100 is 1.00. |
method | Method code for POST /v1/transfers. |
min_amount_minor, max_amount_minor | Limits per transfer, or null if not limited. |
sla_minutes | Time limit for executing a transfer, in minutes, or null if not set. A transfer not completed in time fails with sla_expired. |
recipient_fields | Recipient fields this method requires in POST /v1/transfers, with a short description of each. |
An empty list means no method is available now: the account is not set up for transfers yet, or the fee is not agreed. 403 transfers_disabled means transfers are not enabled for your account.
04 · Create a transfer
POST /v1/transfers
Content-Type: application/json
Idempotency-Key: transfer-77
{
"currency": "CNY",
"method": "alipay",
"amount_minor": 10000,
"recipient_id": "13812341234",
"recipient_name": "ZHANG WEI",
"external_id": "payout-77",
"merchant_order_id": "ORDER-5531",
"external_user_id": "customer-42",
"max_debit_usdt_micro": 15000000
}
Request fields
| Field | Type | Description | |
|---|---|---|---|
currency | string | required | Currency from /v1/transfers/currencies, e.g. CNY. |
method | string | required | Method of this currency, e.g. alipay. |
amount_minor | integer | required | Amount to deliver, in minor units of the currency: CNY in fen, 10000 = 100.00 CNY. Whole amounts are recommended. |
recipient_id | string | required* | Recipient account ID. Alipay: phone number or email. Up to 255 characters. |
recipient_name | string | required* | Recipient name as registered with the method, e.g. ZHANG WEI. Up to 255 characters. |
payment_details | string | optional | Extra details, up to 2048 characters. Does not replace the recipient fields. |
external_id | string | required | Your transfer number: 1–128 characters A–Z a–z 0–9 . _ : -. One transfer per value; a repeated value returns 409 external_id_conflict. |
merchant_order_id | string | optional | Your order number, 1–128 characters, if it differs from external_id. Returned in responses and webhooks; not checked for uniqueness. |
external_user_id | string | required | Your stable ID of the recipient, unique within your store, up to 255 characters. Not an order number: use external_id for that. |
max_debit_usdt_micro | integer | required | The most you agree to be debited, fee included, in millionths of USDT (15000000 = 15 USDT). If the quote is higher, the transfer is not created: 409 debit_limit_exceeded. |
* Required fields depend on the method: see recipient_fields in GET /v1/transfers/currencies. Send each value in its own field; do not combine them into one string.
Response · HTTP 201
{
"id": "TRANSFER_ID",
"external_id": "payout-77",
"merchant_order_id": "ORDER-5531",
"external_user_id": "customer-42",
"currency": "CNY",
"method": "alipay",
"recipient_id": "13812341234",
"recipient_name": "ZHANG WEI",
"amount_minor": 10000,
"status": "processing",
"usdt_amount_micro": 14005603,
"fee_micro": 140056,
"total_debit_usdt_micro": 14145659,
"effective_rate_e6": 7140000,
"rate_source": "USDT/RUB x RUB/CNY",
"failure_reason": null,
"sla_deadline": "2026-11-09T12:30:00+00:00",
"created_at": "2026-11-09T12:00:00+00:00",
"completed_at": null
}
The transfer is sent for execution immediately and starts in processing. If the request times out, repeat it with the same Idempotency-Key and body: you get the same transfer, never a second one. You can also look it up by external_id.
05 · Transfer object
| Field | Description |
|---|---|
id | NOMA transfer ID. |
external_id, external_user_id | Your transfer number and recipient ID. |
merchant_order_id | Your order number, if sent. |
currency, method, amount_minor | What the recipient receives. |
recipient_id, recipient_name | Recipient as sent in the request. |
status | See statuses. |
usdt_amount_micro | Cost of the amount in USDT at the fixed rate. |
fee_micro | NOMA fee in USDT. |
total_debit_usdt_micro | Total debited from the payout deposit on success. |
effective_rate_e6 | Units of the currency per 1 USDT × 1,000,000, after the spread. |
rate_source | How the rate was obtained: USDT/RUB x RUB/CNY is a cross rate. |
failure_reason | null, rejected_by_provider, sla_expired, cancelled_by_merchant or cancelled_by_operator. |
sla_deadline | Deadline for execution, or null. If the transfer is not completed by then, it fails with failure_reason: sla_expired and the reserve returns to the deposit. |
created_at, completed_at | Creation and completion time. |
06 · Get a transfer
GET /v1/transfers/{id}
id — NOMA transfer ID (required). Returns the transfer object. 404 not_found if the transfer does not exist or belongs to another store.
07 · List transfers
GET /v1/transfers?limit=50&offset=0&status=processing
| Parameter | Description | |
|---|---|---|
limit | optional | 1–100, default 50. |
offset | optional | Skip this many transfers, default 0. |
status | optional | Only transfers with this status. |
Returns {"transfers": [ ... ]}, newest first. Sign the path without the query string: /v1/transfers.
08 · Get a transfer by external_id
GET /v1/transfers/by-external-id/{external_id}
external_id — your transfer number (required). Use it to recover a transfer after a lost response.
09 · Cancel a transfer
POST /v1/transfers/{id}/cancel
409 not_cancellable. On success the status becomes cancelled and the reserve returns to the payout deposit.Send the request with an empty body. Returns the transfer object.
10 · Statuses
| Status | Phase | Description |
|---|---|---|
processing | PROGRESS | The transfer is accepted and being executed. Funds are reserved on the deposit. |
needs_review | PROGRESS | The outcome could not be confirmed automatically. NOMA confirms it manually; the reserve stays blocked. |
completed | FINAL | Funds sent to the recipient. The deposit is debited by total_debit_usdt_micro. |
failed | FINAL | The transfer cannot be executed: wrong details, blocked recipient account or other restrictions. The reserve returned. |
cancelled | FINAL | Cancelled by you or by NOMA before execution. The reserve returned. |
NOMA never sends the same transfer twice and never re-sends a transfer whose outcome is unknown.
Time limit. When the method has sla_minutes, each transfer gets sla_deadline. A transfer not executed by then becomes failed (or cancelled) with failure_reason: sla_expired, and the reserve returns to the deposit.
11 · Webhooks
NOMA notifies your webhook URL when a transfer reaches a final status. The body is signed: verify X-Gateway-Signature before changing anything on your side (how).
{
"id": "EVENT_ID",
"type": "transfer.completed",
"created_at": "2026-11-09T12:07:00Z",
"data": {
"id": "TRANSFER_ID",
"external_id": "payout-77",
"status": "completed",
"currency": "CNY",
"method": "alipay",
"amount_minor": 10000,
"total_debit_usdt_micro": 14145659,
...
}
}
| Event | When |
|---|---|
transfer.completed | Funds sent. |
transfer.failed | Transfer failed; reserve returned. |
transfer.cancelled | Transfer cancelled; reserve returned. |
Delivery: up to 10 attempts over about 4 hours; a delivery counts as successful only with an HTTP 2xx response. Deduplicate by event id.
12 · Rate and fee
effective_rate = market rate (currency per USDT) × (1 − spread) usdt_amount = amount / effective_rate (rounded up to 0.000001 USDT) fee = usdt_amount × fee_percent total_debit = usdt_amount + fee
Spread and fee are agreed for your account and fixed in the transfer at creation. Example: 100.00 CNY at 7.14 CNY/USDT with a 1% fee: usdt_amount_micro = 14,005,603, fee_micro = 140,056, total 14.145659 USDT. Set max_debit_usdt_micro with a margin for rate changes.
13 · Errors
{"error": "debit_limit_exceeded", "message": "Quoted total exceeds maximum debit"}
| HTTP | error | Reason | Result |
|---|---|---|---|
| 400 | invalid_request | Request validation failed. | Not executed. No need to re-check. |
| 400 | unsupported_method | Unknown currency/method pair. | Not executed. |
| 400 | invalid_idempotency_key | Missing or too long Idempotency-Key. | Not executed. |
| 401 / 403 | authentication codes | Missing or invalid signature, key or timestamp. | Not executed. |
| 402 | insufficient_funding | The payout deposit does not cover the total. | Not executed, nothing reserved. |
| 403 | transfers_disabled, kyb_required, account_inactive | Transfers are not available for your account. | Not executed. |
| 404 | not_found | Transfer does not exist or belongs to another store. | — |
| 409 | debit_limit_exceeded | The quote exceeds max_debit_usdt_micro. | Not executed, nothing reserved. |
| 409 | external_id_conflict, idempotency_conflict | Number or key already used. | Not executed. |
| 409 | not_cancellable | The transfer is already in work or final. | Not cancelled. |
| 503 | transfer_method_unavailable, payout_fee_not_configured | Method or amount not available for your account now. | Not executed. |
| 503 | rate_unavailable, rate_stale, rate_suspect | The rate is temporarily unavailable. | Not executed. Retry later. |
| timeout | — | No response received. | Not guaranteed. Retry with the same key, or check by external_id. |
14 · Deprecated endpoint
POST /v1/payouts/cny
Earlier integrations created CNY Alipay transfers with POST /v1/payouts/cny (amount_minor, payment_details, external_user_id, max_debit_usdt_micro). It still works and uses the same payout deposit, but sends payout.* webhooks in the QR Payment format and has no external_id. Use POST /v1/transfers for new integrations.