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

# Payouts

> Send money from a book to a beneficiary.

A **payout** debits one of your books and pays a [beneficiary](https://docs.keette.com/guides/beneficiaries.md) on a corridor rail.

## Typical sequence

**1. Ensure a funded book**

`GET /v1/balances` — available must cover amount + fees.

**2. Pick corridor + beneficiary**

[Corridors](https://docs.keette.com/guides/corridors.md) → create or reuse a [beneficiary](https://docs.keette.com/guides/beneficiaries.md).

**3. Optional FX quote**

Cross-currency sends: [firm quote](https://docs.keette.com/guides/fx.md) then pass `quote_id`.

**4. Fee preview**

`POST /v1/payouts/fee` with the same shape you will send.

**5. Create**

`POST /v1/payouts` — returns id and status. Poll `GET /v1/payouts/{id}` or wait for webhooks.

```bash theme={null}
curl https://api.keette.com/v1/payouts \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiary_id": "…",
    "amount": 50000,
    "currency": "NGN",
    "purpose": "salary",
    "idempotency_key": "pay-2026-04-01-ada"
  }'
```

Always send a stable **idempotency key** so retries do not double-send.

## Cancel

`POST /v1/payouts/{id}/cancel` when the payout is still cancellable (see status in the response / webhooks).

## Purposes

`GET /v1/payouts/purposes` lists allowed purpose codes for compliance rails that require one.

## Next

* [Webhooks](https://docs.keette.com/webhooks/overview.md) — `event.payout.*`
* [Transactions](https://docs.keette.com/guides/transactions.md) — unified history
* [API reference — Payouts](https://docs.keette.com/api-reference/payouts)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.