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

Transaction Limits

Most currency and scheme combinations do not enforce fixed transaction limits. However, the schemes listed below enforce the following limits:

Currency	Scheme	Minimum amount	Maximum amount
CNY	Wire	200	35,000,000
HKD	Wire	200	38,000,000
PHP	PESONet	50	18,000,000
PHP	InstaPay	50	50,000

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 /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

string

required

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

string

required

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

string

required

Full legal name of the recipient account holder.

string

required

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

string

required

The ID of the recipient counterparty

string

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

object

Bank address Optional.

Show Bank address fields

string

Street address.

string

City.

string

State or province.

string

Postal code.

string

ISO 3166-1 alpha-2 country code.

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, telkom, vodafone, vodacom, halotel, tigo, nuvion_direct.

object

Optional key-value metadata.

Rail-specific fields

Rail	Currency	Country	Required routing fields
FPS	GBP	GB	`sort_code`, `account_number`, `bank_name`
SEPA	EUR	EU country	`iban`, `bank_name`, `swift_bic`
ACH	USD	US	`scheme: ach`, `routing_number`, `account_number`, `bank_name`, `bank_address`
Wire	USD	US	`scheme: wire`, `routing_number`, `account_number`, `bank_name`, `bank_address`
BECS	AUD	AU	`bank_code`, `branch_code`, `account_number`, `bank_name`
EFT	CAD	CA	`bank_institution_number` (3 digits), `transit_number` (5 digits), `account_number`, `bank_name`
NIP	NGN	NG	`bank_code`, `account_number`, `bank_name`
RTC	ZAR	ZA	`account_number`, `branch_code`, `bank_name`
FAST	SGD	SG	`swift_bic`, `account_number`, `bank_name`
HK FPS	HKD	HK	`bank_code`, `account_number`, `branch_code`, `bank_name`
UAE Local	AED	AE	`iban` (23 characters), `bank_name`
KE EFT	KES	KE	`bank_code`, `account_number`, `bank_name`
UG EFT	UGX	UG	`sort_code` (6 digits), `account_number`, `bank_name`
GH EFT	GHS	GH	`sort_code`, `account_number`, `bank_name`
TZ EFT	TZS	TZ	`sort_code`, `account_number`, `bank_name`
BR TED	BRL	BR	`bank_code`, `account_number`, `branch_code`, `account_type`, `bank_name`
MX SPEI	MXN	MX	`account_number` (18-digit CLABE)
CN Local	CNY	CN	`bank_code`, `account_number`, `bank_name`
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`, `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 schemeSchemes available per currency:TZS: halotel, airtel, tigo, vodacomKES: mpesa, airtel, telkomGHS: mtn, vodafone, airtelUGX: mpesa, airtel

Request examples

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"
  }'

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": "EUR",
    "country": "DE",
    "account_holder_name": "Michael Weber",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "iban": "DE89370400440532013000"
  }'

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": "USD",
    "country": "US",
    "scheme": "ach",
    "account_holder_name": "Danielle Brooks",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "routing_number": "026009593",
    "account_number": "987654321012",
    "account_type": "checking",
    "bank_name": "Bank of America"
  }'

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": "USD",
    "country": "US",
    "scheme": "wire",
    "account_holder_name": "Michael Carter",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "routing_number": "021000021",
    "account_number": "123456789012",
    "account_type": "checking",
    "bank_name": "JPMorgan Chase Bank"
  }'

curl -X POST https://api.nuvion.dev/payment-details \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "momo-transfer",
    "currency": "KES",
    "account_holder_name": "John Smith",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "scheme": "mpesa",
    "phone_number": "+254712345678"
  }'

curl -X POST https://api.nuvion.dev/payment-details \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "stablecoin-transfer",
    "currency": "USC",
    "account_holder_name": "Alex Johnson",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "blockchain_network": "ETH_MAINNET",
    "wallet_address": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
  }'

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": "USD",
    "country": "GB",
    "account_holder_name": "Acme Corp",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "swift_bic": "NWBKGB2L",
    "iban": "GB29NWBK60161331926819",
    "bank_name": "NatWest",
    "bank_address": {
      "line1": "250 Bishopsgate",
      "city": "London",
      "country": "GB"
    }
  }'

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 -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01HXYZ5678EFGH",
    "payment_detail_id": "01KM37FAABC123DEF456GHI789",
    "amount": 10000,
    "currency": "GBP",
    "narration": "Invoice payment INV-2025-001",
    "payment_type": "bank-transfer",
    "unique_reference": "PAY-2025-001"
  }'

string

required

The ID of the source account to debit.

string

required

The id returned by POST /payment-details.

number

required

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

string

required

ISO 4217 currency code. e.g. GBP, USD, EUR, KES. This is the from_currency for cross-currency transfers. See Cross Currency Payouts for cross-currency transfers.

string

required

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

string

required

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

string

required

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

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.

Get Started

Core Concepts

Webhooks

Guides

Supported corridors

Transaction Limits

Step 1: Create a counterparty

Step 2: Add payment details

Base fields

Rail-specific fields

Request examples

Response

Step 3: Initiate the transfer

Transfer statuses

Webhooks

What’s next

Counterparties

Accept a payment

Transfers API reference

​Supported corridors

​Transaction Limits

​Step 1: Create a counterparty

​Step 2: Add payment details

​Base fields

​Rail-specific fields

​Request examples

​Response

​Step 3: Initiate the transfer

​Transfer statuses

​Webhooks

​What’s next

Counterparties

Accept a payment

Transfers API reference

Supported corridors

Transaction Limits

Step 1: Create a counterparty

Step 2: Add payment details

Base fields

Rail-specific fields

Request examples

Response

Step 3: Initiate the transfer

Transfer statuses

Webhooks

What’s next