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
Single Euro Payments Area (SEPA)	EUR	SEPA	Bank transfer	Same day
United States	USD	ACH	Bank transfer	Same / next day
United States	USD	Wire	Bank transfer	Same day
United States	USD	RTP	Bank transfer	Instant
Australia	AUD	BECS	Bank transfer	1–2 business days
Canada	CAD	EFT	Bank transfer	Same / next day
Canada	CAD	Interac (Email)	Bank transfer	Instant
Canada	CAD	Interac (Account)	Bank transfer	Instant
Nigeria	NGN	NIP	Bank transfer	Instant
South Africa	ZAR	RTC	Bank transfer	Same day
Singapore	SGD	FAST	Bank transfer	Instant
Philippines	PHP	PESONet	Bank transfer	Same day
Philippines	PHP	InstaPay	Bank transfer	Instant
Hong Kong	HKD	HK CHATS	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
Mexico	MXN	Clabe	Bank transfer	Instant
China	CNY	Wire	Bank transfer	Same day
Global	Any	SWIFT (IBAN)	Bank transfer	1–3 business days
Global	Any	SWIFT (Acct No.)	Bank transfer	1–3 business days
Multiple	KES / GHS / 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. The schemes listed below do. Minimum and maximum are stated in main currency units for readability only; amount itself is always submitted in the smallest currency unit.

Currency	Scheme	Minimum amount	Maximum amount
CNY	Wire	213	35,593,243
PHP	PESONet	60	18,495,600
PHP	InstaPay	60	50,000
TZS	Mobile money	1,000	5,000,000
KES	Mobile money	20	250,000
GHS	Mobile money	5	25,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": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "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"
      }
    }
  }'

{
  "status": "success",
  "message": "Counterparty created successfully",
  "data": {
    "id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "type": "individual",
    "nickname": "Jane Smith",
    "status": "active",
    "profile": {
      "first_name": "Jane",
      "last_name": "Smith",
      "relationship": "vendor",
      "address": {
        "line1": "123 Main St",
        "city": "Austin",
        "state_or_province": "TX",
        "postal_code": "78701",
        "country": "US"
      },
      "email": "jane.smith@example.com"
    },
    "created": 1787286621446,
    "updated": 1787286621446,
    "deleted": 0
  }
}

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 ach, wire, and rtp).

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

The ID of the entity on whose behalf the payout is being sent. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

required

The ID of the recipient counterparty.

string

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

object

Bank address.

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, wire, or rtp. For CAD, specify eft, interac_email, or interac_account. One of: fps, sepa, ach, wire, rtp, becs, eft, interac_email, interac_account, nip, rtc, fast, pesonet, insta_pay, hk_chats, uae_local, ke_eft, ug_eft, gh_eft, tz_eft, clabe, swift, mpesa, mtn, airtel, telkom, vodafone, vodacom, halotel, tigo, nuvion_direct.

string

Recipient’s email address. Required for the interac_email scheme.

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	SEPA member 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`
RTP	USD	US	`scheme: rtp`, `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`
Interac Email	CAD	CA	`scheme: interac_email`, `email`
Interac Account	CAD	CA	`scheme: interac_account`, `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	`bank_code`, `account_number`, `bank_name`
FAST	SGD	SG	`swift_bic`, `account_number`, `bank_name`
PESONet	PHP	PH	`scheme: pesonet`, `bank_code`, `account_number`
InstaPay	PHP	PH	`scheme: insta_pay`, `bank_code`, `account_number`
HK CHATS	HKD	HK	`bank_code`, `account_number`, `branch_code`, `bank_name`
UAE Local	AED	AE	`iban` (23 characters), `swift_bic`, `bank_name`
KE EFT	KES	KE	`bank_code`, `account_number`, `bank_name`
UG EFT	UGX	UG	`bank_code` (6 digits), `account_number`, `bank_name`
GH EFT	GHS	GH	`bank_code`, `account_number`, `bank_name`
TZ EFT	TZS	TZ	`bank_code`, `account_number`, `bank_name`
Clabe	MXN	MX	`account_number` (18-digit CLABE)
CNY WIRE	CNY	CN	`swift_bic`, `account_number`, `bank_name`
SWIFT (IBAN)	Any	Any	`swift_bic`, `iban`, `bank_name`, `bank_address`
SWIFT (Acct No.)	Any	Any	`swift_bic`, `account_number`, `bank_name`
Mobile money	KES / GHS / TZS	—	`scheme`, `phone_number`, `country`
Stablecoin	USC / UST	—	`blockchain_network` (`ETH_MAINNET` / `SOLANA_MAINNET` / `BASE_MAINNET` / `POLYGON_MAINNET`), `wallet_address`
Book transfer	Any	Any	`account_number`

Schemes available per currency:TZS: halotel, airtel, tigo, vodacomKES: mpesa, airtel, telkomGHS: mtn, vodafone, 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": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "sort_code": "040004",
    "account_number": "12345678",
    "bank_name": "Barclays"
  }'

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": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "iban": "DE89370400440532013000",
    "bank_name": "Commerzbank",
    "swift_bic": "COBADEFFXXX"
  }'

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": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "routing_number": "026009593",
    "account_number": "987654321012",
    "account_type": "checking",
    "bank_name": "Bank of America",
    "bank_address": {
      "line1": "100 Federal Street",
      "city": "Boston",
      "state": "MA",
      "postal_code": "02110",
      "country": "US"
    }
  }'

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": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "routing_number": "021000021",
    "account_number": "123456789012",
    "account_type": "checking",
    "bank_name": "JPMorgan Chase Bank",
    "bank_address": {
      "line1": "270 Park Avenue",
      "city": "New York",
      "state": "NY",
      "postal_code": "10017",
      "country": "US"
    }
  }'

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": "rtp",
    "account_holder_name": "Sarah Mitchell",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "routing_number": "121000248",
    "account_number": "112233445566",
    "account_type": "checking",
    "bank_name": "Wells Fargo Bank",
    "bank_address": {
      "line1": "420 Montgomery Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94104",
      "country": "US"
    }
  }'

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": "CAD",
    "country": "CA",
    "scheme": "interac_email",
    "account_holder_name": "Olivia Bennett",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "email": "olivia.bennett@example.com"
  }'

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": "CAD",
    "country": "CA",
    "scheme": "interac_account",
    "account_holder_name": "Lucas Tremblay",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "bank_institution_number": "003",
    "transit_number": "12345",
    "account_number": "7891234",
    "bank_name": "Royal Bank of Canada"
  }'

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": "NGN",
    "country": "NG",
    "account_holder_name": "Chidinma Okafor",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "bank_code": "044",
    "account_number": "0690000031",
    "bank_name": "Access Bank"
  }'

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": "MXN",
    "country": "MX",
    "scheme": "clabe",
    "account_holder_name": "Camila Torres",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "account_number": "002180000123456789"
  }'

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": "CNY",
    "country": "CN",
    "account_holder_name": "Zhang Wei",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "swift_bic": "SYCBCNBYXXX",
    "account_number": "6230810325651744",
    "bank_name": "SHENGJING BANK CO.,LTD"
  }'

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",
    "country": "KE",
    "account_holder_name": "John Smith",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "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": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "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": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "swift_bic": "NWBKGB2L",
    "iban": "GB29NWBK60161331926819",
    "bank_name": "NatWest",
    "bank_address": {
      "line1": "250 Bishopsgate",
      "city": "London",
      "state": "England",
      "postal_code": "EC2M 4AA",
      "country": "GB"
    }
  }'

Response

{
  "status": "success",
  "message": "Payment detail created successfully",
  "data": {
    "id": "01HXYZ0061ABCDEFGHJKMNPQRS",
    "payment_method": "bank-transfer",
    "currency": "GBP",
    "account_holder_name": "Jane Smith",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "scheme": "fps",
    "account_number": "12345678",
    "country": "GB",
    "sort_code": "040004",
    "bank_name": "Barclays"
  }
}

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 initiating the transfer, then include fx_quote_id below. See Cross Currency Payouts for the full flow.

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": "01HXYZ0064ABCDEFGHJKMNPQRS",
    "payment_detail_id": "01HXYZ0061ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "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.

string

required

The ID of the recipient counterparty. Returned by POST /counterparties.

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.

string

required

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

string

required

The payment type of the transfer. One of bank-transfer, momo-transfer, stablecoin-transfer, or book-transfer.

string

required

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

string

The ID of an FX quote from POST /fx-quotes. Required when the source account currency differs from the transfer currency. See Cross Currency Payouts.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

object

Optional key-value metadata.

{
    "status": "success",
    "message": "Transfer created successfully",
    "data": {
        "id": "01HXYZ0060ABCDEFGHJKMNPQRS",
        "amount": 10000,
        "currency": "GBP",
        "unique_reference": "PAY-2025-001",
        "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
        "account_id": "01HXYZ0064ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
        "status": "pending",
        "status_reason": "awaiting_processing",
        "narration": "Invoice payment INV-2025-001",
        "type": "outflow",
        "payment_type": "bank-transfer",
        "applicable_fee": 50,
        "meta": {},
        "created": 1787415765559,
        "updated": 1787415765559
    }
}

Transfer statuses

Status	Description
`pending`	Transfer created, awaiting processing
`processing`	Being executed by the payment network
`successful`	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 ₦100.00 NGN.

Webhooks

Transfers are asynchronous: the response you get back from POST /transfers reflects the initial pending state, not the final outcome. Subscribe to outflows.created, outflows.completed, outflows.failed, and outflows.cancelled to track a transfer as it moves through the statuses above. See Event types for the full payload schema.

Verify the transfer’s status with GET /transfers/{transfer_id} before treating a payout as complete, rather than relying on the webhook payload alone. See Verifying webhook signatures to confirm the event itself is genuine.

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