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

# Send Payouts

> Pay bank accounts, mobile money wallets, and on-chain addresses from your Rolla wallet

All payouts flow through one endpoint — [Withdraw Funds](/api-reference/endpoint/wallet/withdraw). The beneficiary's `withdrawal_method` decides the rail: USD over SWIFT to 185+ countries, US ACH and domestic wires, local bank transfers, mobile money, or USDC/USDT on-chain. The flow is the same shape whatever currency you're sending — this guide walks it once, then shows the two most common paths side by side.

<Warning>
  Every API key needs at least one [allowlisted IP](/concepts/authentication#ip-allowlisting) — set that up first if you haven't already.
</Warning>

## 1. Quote the fee (optional but recommended)

```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/fee" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "transactionType": "withdrawal",
    "amount": 10000
  }'
```

By default fees come out of your wallet balance and the beneficiary receives the exact amount you asked for; pass `deductFeesFromBalance: false` on the withdrawal if the fee should come out of the amount you send instead.

## 2. Resolve the beneficiary and send

This is the one step that differs by currency and rail — pick your path:

<Tabs>
  <Tab title="USD payout">
    For USD, create the beneficiary with their SWIFT/BIC and account number (or IBAN). No name-lookup step exists for international rails — Create Beneficiary validates the fields, not the identity of the account holder.

    ```bash theme={null}
    curl -X POST "https://api.rolla.xyz/api/v1/external/beneficiaries" \
      -H "X-API-Key: your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "currency": "USD",
        "withdrawal_method": "international_wire",
        "account_name": "ACME GMBH",
        "account_number": "DE89370400440532013000",
        "swift_code": "COBADEFFXXX",
        "bank_name": "Commerzbank AG",
        "account_owner_type": "business",
        "account_category": "checking",
        "bank_address": { "street": "Kaiserplatz 16", "city": "Frankfurt", "state": "Hessen", "postalCode": "60311", "country": "DE" },
        "beneficiary_address": { "street": "Hauptstrasse 1", "city": "Berlin", "state": "Berlin", "postalCode": "10827", "country": "DE" }
      }'
    ```

    Then send it — `amount` is in cents, so `10000` = \$100.00:

    ```bash theme={null}
    curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/withdraw" \
      -H "X-API-Key: your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 10000,
        "currency": "USD",
        "beneficiaryId": "BENEFICIARY_ID",
        "description": "Invoice 4021",
        "externalReference": "payout-4021"
      }'
    ```

    For US domestic rails (`ach` / `domestic_wire`), swap in `routing_number` and drop `swift_code`/`iban` — see [Create Beneficiary](/api-reference/endpoint/beneficiaries/create) for the exact fields per method, and the [SWIFT payouts guide](/swift-payouts) for worldwide country coverage.
  </Tab>

  <Tab title="Local currency payout (e.g. NGN)">
    For local rails, verify the account first — it returns the registered account name so you (or your user) can confirm it's the right person:

    ```bash theme={null}
    curl -X POST "https://api.rolla.xyz/api/v1/external/lookup" \
      -H "X-API-Key: your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{ "bankCode": "000014", "accountNumber": "0123456789" }'
    ```

    Bank codes come from [List Banks](/api-reference/endpoint/banks). Then create the beneficiary:

    ```bash theme={null}
    curl -X POST "https://api.rolla.xyz/api/v1/external/beneficiaries" \
      -H "X-API-Key: your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "currency": "NGN",
        "label": "Supplier — Lagos",
        "account_name": "JOHN DOE",
        "account_number": "0123456789",
        "bank_name": "Access Bank",
        "bank_code": "000014"
      }'
    ```

    And send it — `amount` is in kobo, so `100000` = ₦1,000:

    ```bash theme={null}
    curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/withdraw" \
      -H "X-API-Key: your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 100000,
        "currency": "NGN",
        "beneficiaryId": "BENEFICIARY_ID",
        "description": "Invoice 4021",
        "externalReference": "payout-4021"
      }'
    ```
  </Tab>
</Tabs>

<Tip>
  Prefer not to save a beneficiary for a one-off payout? Both paths accept `inlineBeneficiary` directly on the withdrawal instead of a `beneficiaryId` — add `saveBeneficiary: true` to keep it for next time.
</Tip>

Either way, remember: `amount` is always in [minor units](/concepts/amounts-and-currencies) of `currency`, and on USD rails you should set an `externalReference` so you can [recover safely from timeouts](/concepts/idempotency).

<Warning>
  **NGN and mobile money ignore `externalReference`.** Those rails mint their own (`NG-XXXXXXXX` / `MM-XXXXXXXX`), so the value you send is not stored and looking it up later returns `404`. Put your own identifier in `metadata` instead and recover by listing recent transactions. See [Idempotency & Retries](/concepts/idempotency).
</Warning>

<Info>
  **Platforms:** add the `X-Account-Id` header to pay out from a customer's wallet instead of your own. See [Operate Customer Accounts](/platform/operate-accounts).
</Info>

## 3. Track to completion

The response gives you the transaction `id` immediately, but a payout is only done when it reaches a terminal status. Subscribe to [webhooks](/api-reference/webhooks/overview):

* `transaction.completed` — the beneficiary was paid
* `transaction.failed` / `transaction.rejected` — the payout didn't go through and **funds are back in your wallet**
* `transaction.uetr.assigned` — for SWIFT payouts, the network tracing reference ([more](/swift-payouts#tracing-a-payout-the-uetr))

Or fetch on demand with [Get Transaction](/api-reference/endpoint/wallet/get-transaction) by `id`, or by your `externalReference` on the rails that store it. On NGN and mobile money, look the payout up by the `id` you were returned, or match your `metadata` against [List Transactions](/api-reference/endpoint/wallet/transactions).

## Pay under an affiliated name

A payout goes out under your own business name by default. With
[Named Payouts](/guides/named-payouts) enabled, you can also register affiliated payer names — a
related entity of yours, or the end-customer you are paying for — and pick one per payout with
`payerNameId`.

This applies to **USD international wire payouts only** — the beneficiary's `withdrawal_method`
must be `international_wire`. On any other rail the payout is refused with a `400`. Because
international wire is sent as `multipart/form-data`, a named payout is always a multipart request:

```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/withdraw" \
  -H "X-API-Key: your_api_key_here" \
  -F "amount=250000" \
  -F "currency=USD" \
  -F "description=Invoice 2291" \
  -F "beneficiaryId=c3d4e5f6-a7b8-9012-cdef-123456789012" \
  -F "payerNameId=9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f" \
  -F "documents=@/path/to/invoice.pdf"
```

Set a default payer name instead and every international wire payout that omits `payerNameId` uses
it, with no change to your payout code; leave both unset and the payout carries your own business name.
Affiliated names are reviewed and registered before they can be used, so read the
[Named Payouts guide](/guides/named-payouts) before you build against it.

## Other destinations

* **Mobile money** — select corridors (e.g. XAF, XOF, GHS) via `withdrawal_method: "mobile_money"` with `mobile_money_provider` and `phone_number`.
* **Stablecoins** — `crypto_usdc` / `crypto_usdt` with `wallet_address` and `wallet_chain`.
* **Another Rolla business** — skip beneficiaries entirely and use [Rolla Transfer](/api-reference/endpoint/wallet/transfer) for instant transfers between Rolla accounts.

See [Amounts & Currencies](/concepts/amounts-and-currencies#currencies-you-can-pay-out-in) for the full list of destination currencies.