> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuvion.co/llms.txt
> Use this file to discover all available pages before exploring further.

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

***

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

***

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

## 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`.

<CodeGroup>
  ```bash curl theme={null}
  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"
        }
      }
    }'
  ```
</CodeGroup>

```json theme={null}
{
  "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.

<Note>
  Counterparties also support `type: "business"`. See the [Counterparties guide](/core-concepts/counterparties) for the full schema.
</Note>

***

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

<ParamField body="payment_method" type="string" required>
  The transfer method. One of `bank-transfer`, `momo-transfer`, `stablecoin-transfer`, or `book-transfer`.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code. e.g. `GBP`, `USD`, `EUR`, `KES`.
</ParamField>

<ParamField body="account_holder_name" type="string" required>
  Full legal name of the recipient account holder.
</ParamField>

<ParamField body="entity_id" type="string" required>
  The ID of the entity on whose behalf the payout is being sent.
</ParamField>

<ParamField body="counterparty_id" type="string" required>
  The ID of the recipient counterparty
</ParamField>

<ParamField body="country" type="string">
  ISO 3166-1 alpha-2 destination country code. Required for all bank transfer rails. e.g. `US`, `GB`, `DE`.
</ParamField>

<ParamField body="bank_address" type="object" optional>
  Bank address Optional.

  <Expandable title="Bank address fields">
    <ParamField body="line1" type="string">
      Street address.
    </ParamField>

    <ParamField body="city" type="string">
      City.
    </ParamField>

    <ParamField body="state" type="string">
      State or province.
    </ParamField>

    <ParamField body="postal_code" type="string">
      Postal code.
    </ParamField>

    <ParamField body="country" type="string">
      ISO 3166-1 alpha-2 country code.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="scheme" type="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`.
</ParamField>

<ParamField body="meta" type="object">
  Optional key-value metadata.
</ParamField>

### 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`                                                                                               |

<Note>
  For mobile money, `country` is not required — Nuvion infers the destination from `currency` and `scheme`

  Schemes available per currency:

  TZS: `halotel`, `airtel`, `tigo`, `vodacom`

  KES: `mpesa`, `airtel`, `telkom`

  GHS: `mtn`, `vodafone`, `airtel`

  UGX: `mpesa`, `airtel`
</Note>

### Request examples

<CodeGroup>
  ```bash FPS — GBP theme={null}
  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"
    }'
  ```

  ```bash SEPA — EUR theme={null}
  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"
    }'
  ```

  ```bash ACH — USD theme={null}
  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"
    }'
  ```

  ```bash Wire — USD theme={null}
  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"
    }'
  ```

  ```bash Mobile money — M-Pesa theme={null}
  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"
    }'
  ```

  ```bash Stablecoin — USC theme={null}
  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"
    }'
  ```

  ```bash SWIFT — IBAN theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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

<Info>
  For cross currency payments,  obtain an FX quote before intitiating the transfer. See [Cross Currency Payouts](./cross-currency-payouts) for full details.
</Info>

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.

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```
</CodeGroup>

***

<ParamField body="account_id" type="string" required>
  The ID of the source account to debit.
</ParamField>

<ParamField body="payment_detail_id" type="string" required>
  The `id` returned by `POST /payment-details`.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount in the smallest currency unit. `10000` = \$100.00 USD or £100.00 GBP.
</ParamField>

<ParamField body="currency" type="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](./cross-currency-payouts) for cross-currency transfers.
</ParamField>

<ParamField body="narration" type="string" required>
  Transfer description. Passed to the recipient's bank statement where supported.
</ParamField>

<ParamField body="payment_type" type="string" required>
  The payment type of the transfer. It can be bank-transfer, momo-transfer, stablecoin-transfer, and book-transfer.
</ParamField>

<ParamField body="unique_reference" type="string" required>
  Idempotency key. Resubmitting the same reference returns the original transfer rather than creating a duplicate.
</ParamField>

<ParamField body="meta" type="object">
  Optional key-value metadata.
</ParamField>

```json theme={null}
{
  "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  |

<Note>
  All amounts are in the **smallest currency unit**. `10000` = \$100.00 USD, £100.00 GBP, or ₦10,000 NGN.
</Note>

***

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

<CardGroup cols={3}>
  <Card title="Counterparties" icon="users" href="/core-concepts/counterparties">
    Full counterparty management — create, update, list, and deactivate.
  </Card>

  <Card title="Accept a payment" icon="arrow-down-to-line" href="/guides/accept-a-payment">
    Receive funds into an account via bank transfer.
  </Card>

  <Card title="Transfers API reference" icon="code" href="/api-reference/transfers">
    Full endpoint documentation for transfers.
  </Card>
</CardGroup>