Send a Payout

Register a counterparty, attach their payment details, and initiate payouts across 24+ payment rails globally.

Nuvion supports payouts to bank accounts, mobile money wallets, stablecoin addresses, and other Nuvion accounts across 100+ currencies. All payouts follow the same three-step flow: create a counterparty, attach their payment routing details, then initiate the transfer.

Supported corridors

Destination	Currency	Scheme	Method	Settlement
United Kingdom	GBP	FPS	Bank transfer	Same day
Euro zone	EUR	SEPA	Bank transfer	Same day
United States	USD	ACH	Bank transfer	Same / next day
United States	USD	Wire	Bank transfer	Same day
Australia	AUD	BECS	Bank transfer	1–2 business days
Canada	CAD	EFT	Bank transfer	Same / next day
Nigeria	NGN	NIP	Bank transfer	Instant
South Africa	ZAR	RTC	Bank transfer	Same day
Singapore	SGD	FAST	Bank transfer	Instant
Hong Kong	HKD	HK FPS	Bank transfer	Instant
United Arab Emirates	AED	UAE Local	Bank transfer	Same / next day
Kenya	KES	EFT	Bank transfer	Same day
Uganda	UGX	EFT	Bank transfer	Same day
Ghana	GHS	EFT	Bank transfer	Same day
Tanzania	TZS	EFT	Bank transfer	Same day
Brazil	BRL	TED	Bank transfer	Same day
Mexico	MXN	SPEI	Bank transfer	Instant
China	CNY	Local	Bank transfer	Same day
CEMAC zone	XAF	CEMAC	Bank transfer	1–2 business days
Global	Any	SWIFT (IBAN)	Bank transfer	1–3 business days
Global	Any	SWIFT (Acct No.)	Bank transfer	1–3 business days
Multiple	KES / GHS / UGX / TZS	Mobile money	MoMo transfer	Instant
Multiple	USC / UST	Stablecoin	Stablecoin transfer	Near-instant
Multiple	Any	Nuvion Direct	Book transfer	Instant

Counterparties and payment details are reusable. Create them once per recipient and reference the same IDs for all future transfers.

---

Step 1: Create a counterparty

A counterparty represents the recipient — their identity (name, address, email) lives here, separate from their banking details. Use POST /counterparties.

curl

curl -X POST https://api.nuvion.dev/counterparties \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "profile": {
      "first_name": "Jane",
      "last_name": "Smith",
      "relationship": "vendor",
      "email": "[e-mail]",
      "address": {
        "line1": "123 Main St",
        "city": "Austin",
        "state_or_province": "TX",
        "postal_code": "78701",
        "country": "US"
      }
    }
  }'

{
  "id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
  "type": "individual",
  "nickname": "Jane Smith",
  "status": "active",
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith",
    "relationship": "vendor",
    "email": "[e-mail]",
    "address": {
      "line1": "123 Main St",
      "city": "Austin",
      "state_or_province": "TX",
      "postal_code": "78701",
      "country": "US"
    }
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}

Save the id — you’ll use it as counterparty_id throughout the remaining steps.

Counterparties also support type: "business". See the Counterparties guide for the full schema.

---

Step 2: Add payment details

Attach the counterparty’s banking or wallet routing information using POST /payment-details. The scheme is inferred automatically from currency and country for most rails — set scheme explicitly only when a currency supports multiple options (e.g. USD supports both ach and wire).

Base fields

payment_method · string · required

The transfer method. One of bank-transfer, momo-transfer, stablecoin-transfer, or book-transfer.

currency · string · required

ISO 4217 currency code. e.g. GBP, USD, EUR, KES.

account_holder_name · string · required

Full legal name of the recipient account holder.

entity_id · string · required

The ID of the entity on whose behalf the payout is being sent.

counterpaty_id · string · required

The ID of the recipient counterparty

country · string

ISO 3166-1 alpha-2 destination country code. Required for all bank transfer rails. e.g. US, GB, DE.

scheme · string

The payment scheme. Required only when a currency supports multiple schemes. For USD, specify ach or wire. One of: fps, sepa, ach, wire, becs, eft, nip, rtc, fast, hk_fps, uae_local, ke_eft, ug_eft, gh_eft, tz_eft, br_ted, mx_spei, cn_local, cemac, swift, mpesa, mtn, airtel, orange, wave, tigo, nuvion_direct.

meta · object

Optional key-value metadata.

Request examples

FPS — GBP

curl -X POST https://api.nuvion.dev/payment-details \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "bank-transfer",
    "currency": "GBP",
    "country": "GB",
    "account_holder_name": "Jane Smith",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "sort_code": "040004",
    "account_number": "12345678"
  }'

Rail-specific fields

Rail	Currency	Country	Required routing fields
FPS	GBP	GB	sort_code, account_number
SEPA	EUR	EU country	iban
ACH	USD	US	scheme: ach, routing_number, account_number, bank_name
Wire	USD	US	scheme: wire, routing_number, account_number, bank_name
BECS	AUD	AU	bank_code, branch_code, account_number
EFT	CAD	CA	bank_institution_number (3 digits), transit_number (5 digits), account_number, bank_name
NIP	NGN	NG	bank_code, account_number
RTC	ZAR	ZA	account_number, branch_code
FAST	SGD	SG	swift_bic, account_number
HK FPS	HKD	HK	bank_code, account_number, branch_code
UAE Local	AED	AE	iban (23 characters)
KE EFT	KES	KE	sort_code (5 digits), account_number
UG EFT	UGX	UG	sort_code (6 digits), account_number
GH EFT	GHS	GH	sort_code, account_number
TZ EFT	TZS	TZ	sort_code, account_number
BR TED	BRL	BR	bank_code, account_number, branch_code, account_type
MX SPEI	MXN	MX	account_number (18-digit CLABE)
CN Local	CNY	CN	bank_code, account_number
CEMAC	XAF	CM / CF / TD / CG / GQ / GA	account_number (23 characters)
SWIFT (IBAN)	Any	Any	swift_bic, iban, bank_name
SWIFT (Acct No.)	Any	Any	swift_bic, account_number, bank_name
Mobile money	KES / GHS / UGX / TZS	—	scheme (mpesa / mtn / airtel / orange / wave / tigo), phone_number
Stablecoin	USC / UST	—	blockchain_network (ETH_MAINNET / SOLANA_MAINNET / BASE_MAINNET / POLYGON_MAINNET), wallet_address
Book transfer	Any	Any	account_number

For mobile money, country is not required — Nuvion infers the destination from currency and scheme.

Response

{
  "id": "pd_01KM37FAABC123DEF456GHI789",
  "payment_method": "bank-transfer",
  "currency": "GBP",
  "country": "GB",
  "scheme": "fps",
  "account_holder_name": "Jane Smith",
  "sort_code": "040004",
  "account_number": "12345678",
  "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS"
}

Save the id — pass it as payment_detail_id when initiating the transfer.

---

Step 3: Initiate the transfer

For cross currency payments, obtain an FX quote before intitiating the transfer. See Cross Currency Payouts for full details.

With payment details registered, initiate the payout. Use POST /transfers for bank and SWIFT rails, mobile money, and for stablecoin sends. Use specific payment type to specify the type of payment.

curl

curl -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HXYZ5678EFGH",
    "payment_detail_id": "pd_01KM37FAABC123DEF456GHI789",
    "amount": 10000,
    "narration": "Invoice payment INV-2025-001",
    "payment_type" "bank-transfer",
    "unique_reference": "PAY-2025-001"
  }'

---

account_id · string · required

The ID of the source account to debit.

payment_detail_id · string · required

The id returned by POST /counterparties/{counterparty_id}/payment-details.

amount · number · required

Amount in the smallest currency unit. 10000 = $100.00 USD or £100.00 GBP.

narration · string · required

Transfer description. Passed to the recipient’s bank statement where supported.

payment_type · string · required

The payment type of the transfer. It can be bank-transfer, momo-transfer, stablecoin-transfer, and book-transfer.

unique_reference · string · required

Idempotency key. Resubmitting the same reference returns the original transfer rather than creating a duplicate.

meta · object

Optional key-value metadata.

{
  "id": "txf_01HJ5G6R7MXW5ZK2QD6YA8N9F3",
  "account_id": "acc_01HXYZ5678EFGH",
  "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
  "payment_detail_id": "pd_01KM37FAABC123DEF456GHI789",
  "type": "outflow",
  "currency": "GBP",
  "amount": 10000,
  "applicable_fee": 50,
  "status": "pending",
  "status_reason": "awaiting_processing",
  "narration": "Invoice payment INV-2025-001",
  "unique_reference": "PAY-2025-001",
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}

---

Transfer statuses

Status	Description
pending	Transfer created, awaiting processing
processing	Being executed by the payment network
completed	Successfully delivered to the recipient
failed	Transfer could not be completed
reversed	Transfer was reversed after completion

All amounts are in the smallest currency unit. 10000 = $100.00 USD, £100.00 GBP, or ₦10,000 NGN.

---

Webhooks

Listen for transfers.updated to track status changes in real time. Nuvion fires this event each time a transfer moves to a new status.

---

What’s next

Counterparties

Full counterparty management — create, update, list, and deactivate.

Accept a payment

Receive funds into an account via bank transfer.

Transfers API reference

Full endpoint documentation for transfers.