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

# Send a payout

> Validate, send, and confirm — including cross-currency and crypto destinations.

A payout moves money from one of your balances to a bank account, mobile money wallet, or crypto address. The whole flow is three calls and a webhook.

## 1. Find the method

Every destination is addressed by a **method code** from the capabilities catalog — `gh_mtn`, `ng_gtbank`, `ke_mpesa`. The catalog also tells you what fields the method needs, its limits, and how long it settles.

```bash theme={null}
GET /v1/capabilities/NG
```

## 2. Validate the destination

Resolve the account holder before you send. It's free on sandbox, cheap on production, and catches the transposed digit that would otherwise pay a stranger.

```bash theme={null}
POST /v1/validate
{ "code": "ng_gtbank", "accountNumber": "0123456789" }
→ { "validation": { "valid": true, "accountName": "ADAEZE OKAFOR" } }
```

For crypto, validation checks the address format for the chain. `POST /v1/validate/bulk` takes up to 100.

## 3. Send

```bash theme={null}
POST /v1/payouts
{
  "to": {
    "code": "ng_gtbank",
    "accountNumber": "0123456789",
    "amount": 45000,
    "currency": "NGN",
    "recipient": { "name": "Adaeze Okafor" }
  },
  "narration": "Website build — final",
  "externalReference": "inv-1042",
  "metadata": { "invoiceId": "1042" }
}
```

`201` returns the payout in `pending`; `200` means this `externalReference` was already used and you're seeing the original — see [Idempotency](/concepts/idempotency).

### Which side carries the amount

Exactly one of `to.amount` or `from.amount`:

* **`to.amount`** — "deliver exactly this much." The most common case. Your balance is debited whatever that costs.
* **`from.amount`** + `from.currency` — "debit exactly this much from this balance." Use it for cross-currency payouts: `from: { amount: 100, currency: "USD" }` to a GHS destination converts at the live rate and delivers the result.

### Saved recipients

If you pay the same destination repeatedly, create it once with `POST /v1/recipients` — validation happens at creation and the holder name is stored. Then reference it by its details as above; the API matches it to the saved recipient.

### Crypto destinations

Use `to.address` instead of `to.accountNumber`, and `to.tag` for chains that need a memo (Stellar, Ripple). The asset and chain come from the method code (e.g. `usdc_solana`). Amounts are in the asset; cross-currency from a fiat balance is priced at the live rate.

## 4. Confirm

Subscribe to **`payout.completed`** and **`payout.failed`**. A failed payout carries `statusMessage` and has **already refunded your balance** — nothing to unwind. For a one-off check, `GET /v1/payouts/{id}` includes `attempts` (each provider try) and `timeline` (the full audit trail).

## Things that bite

* Zero-decimal currencies (UGX, TZS, RWF) reject fractional amounts.
* Each method has `limits.min` / `limits.max`; your organization may also have daily/monthly caps (`payout_limit_exceeded`).
* On sandbox the amount's cents choose the outcome — `150.07` goes pending and then fails. See [Sandbox](/sandbox).
* KYC objects (`from.kyc`, `to.kyc`) are accepted and echoed back; requirements vary by corridor — we'll tell you if a specific corridor needs them.