NOMA / DEVELOPERSMerchant dashboard ↗

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.

CurrencyMethodRecipient
CNY · Chinese yuanalipay · AlipayAlipay account
  1. Top up your payout deposit in USDT.
  2. Get the available currencies and methods: GET /v1/transfers/currencies.
  3. Create a transfer with your own external_id: POST /v1/transfers. NOMA fixes the rate and fee and reserves the total on the deposit.
  4. Track the status with transfer.* webhooks and GET /v1/transfers/{id} or GET /v1/transfers/by-external-id/{external_id}.
Every request is signed with x-api-key, x-timestamp and x-signature; POST /v1/transfers also needs Idempotency-Key. See Getting started → Authentication.

01 · System information

API serverhttps://api.nomapay.io
Dashboardnomapay.io/cabinet — API keys, webhook URL, operations.
FormatJSON over HTTPS. Amounts are integers in minor units of the currency; USDT in millionths.
MethodPathPurpose
GET/v1/transfers/currenciesAvailable currencies and methods
POST/v1/transfersCreate a transfer
GET/v1/transfers/{id}Get a transfer by NOMA ID
GET/v1/transfersList transfers
GET/v1/transfers/by-external-id/{external_id}Get a transfer by your number
POST/v1/transfers/{id}/cancelCancel a transfer
GET/v1/balancesBalances, 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).

The payout deposit is separate from the payQR deposit used for QR payments. Funds never move between them automatically.

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}
          ]
        }
      ]
    }
  ]
}
FieldDescription
currencyISO 4217 code: use it in POST /v1/transfers.
minor_unitsDecimal places: 2 means amount_minor = 100 is 1.00.
methodMethod code for POST /v1/transfers.
min_amount_minor, max_amount_minorLimits per transfer, or null if not limited.
sla_minutesTime limit for executing a transfer, in minutes, or null if not set. A transfer not completed in time fails with sla_expired.
recipient_fieldsRecipient 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

FieldTypeDescription
currencystringrequiredCurrency from /v1/transfers/currencies, e.g. CNY.
methodstringrequiredMethod of this currency, e.g. alipay.
amount_minorintegerrequiredAmount to deliver, in minor units of the currency: CNY in fen, 10000 = 100.00 CNY. Whole amounts are recommended.
recipient_idstringrequired*Recipient account ID. Alipay: phone number or email. Up to 255 characters.
recipient_namestringrequired*Recipient name as registered with the method, e.g. ZHANG WEI. Up to 255 characters.
payment_detailsstringoptionalExtra details, up to 2048 characters. Does not replace the recipient fields.
external_idstringrequiredYour 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_idstringoptionalYour order number, 1–128 characters, if it differs from external_id. Returned in responses and webhooks; not checked for uniqueness.
external_user_idstringrequiredYour 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_microintegerrequiredThe 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

FieldDescription
idNOMA transfer ID.
external_id, external_user_idYour transfer number and recipient ID.
merchant_order_idYour order number, if sent.
currency, method, amount_minorWhat the recipient receives.
recipient_id, recipient_nameRecipient as sent in the request.
statusSee statuses.
usdt_amount_microCost of the amount in USDT at the fixed rate.
fee_microNOMA fee in USDT.
total_debit_usdt_microTotal debited from the payout deposit on success.
effective_rate_e6Units of the currency per 1 USDT × 1,000,000, after the spread.
rate_sourceHow the rate was obtained: USDT/RUB x RUB/CNY is a cross rate.
failure_reasonnull, rejected_by_provider, sla_expired, cancelled_by_merchant or cancelled_by_operator.
sla_deadlineDeadline 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_atCreation 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
ParameterDescription
limitoptional1–100, default 50.
offsetoptionalSkip this many transfers, default 0.
statusoptionalOnly 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
Cancellation is possible only until the transfer is taken into work by the payment network. After that, 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

StatusPhaseDescription
processingPROGRESSThe transfer is accepted and being executed. Funds are reserved on the deposit.
needs_reviewPROGRESSThe outcome could not be confirmed automatically. NOMA confirms it manually; the reserve stays blocked.
completedFINALFunds sent to the recipient. The deposit is debited by total_debit_usdt_micro.
failedFINALThe transfer cannot be executed: wrong details, blocked recipient account or other restrictions. The reserve returned.
cancelledFINALCancelled 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,
    ...
  }
}
EventWhen
transfer.completedFunds sent.
transfer.failedTransfer failed; reserve returned.
transfer.cancelledTransfer 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"}
HTTPerrorReasonResult
400invalid_requestRequest validation failed.Not executed. No need to re-check.
400unsupported_methodUnknown currency/method pair.Not executed.
400invalid_idempotency_keyMissing or too long Idempotency-Key.Not executed.
401 / 403authentication codesMissing or invalid signature, key or timestamp.Not executed.
402insufficient_fundingThe payout deposit does not cover the total.Not executed, nothing reserved.
403transfers_disabled, kyb_required, account_inactiveTransfers are not available for your account.Not executed.
404not_foundTransfer does not exist or belongs to another store.—
409debit_limit_exceededThe quote exceeds max_debit_usdt_micro.Not executed, nothing reserved.
409external_id_conflict, idempotency_conflictNumber or key already used.Not executed.
409not_cancellableThe transfer is already in work or final.Not cancelled.
503transfer_method_unavailable, payout_fee_not_configuredMethod or amount not available for your account now.Not executed.
503rate_unavailable, rate_stale, rate_suspectThe 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.