Send a Payout

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 -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": "jane.smith@example.com",
      "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": "jane.smith@example.com",
    "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 /counterparties/{counterparty_id}/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.

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.

Request examples

curl -X POST https://api.nuvion.dev/counterparties/01KM37EZ0AYCVDXJ3WDHXPPSZ9/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",
    "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

With payment details registered, initiate the payout. Use POST /bank-transfers for bank and SWIFT rails, POST /momo-transfers for mobile money, and POST /stablecoin-transfers for stablecoin sends.

curl -X POST https://api.nuvion.dev/bank-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",
    "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.

unique_reference

string

required

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

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.

Get Started

Core Concepts

Webhooks

Guides

Supported corridors

Step 1: Create a counterparty

Step 2: Add payment details

Base fields

Request examples

Rail-specific fields

Response

Step 3: Initiate the transfer

Transfer statuses

Webhooks

What’s next

Counterparties

Accept a payment

Transfers API reference

Get Started

Core Concepts

Webhooks

Guides

​Supported corridors

​Step 1: Create a counterparty

​Step 2: Add payment details

​Base fields

​Request examples

​Rail-specific fields

​Response

​Step 3: Initiate the transfer

​Transfer statuses

​Webhooks

​What’s next

Counterparties

Accept a payment

Transfers API reference

Supported corridors

Step 1: Create a counterparty

Step 2: Add payment details

Base fields

Request examples

Rail-specific fields

Response

Step 3: Initiate the transfer

Transfer statuses

Webhooks

What’s next