Payouts

A payout debits one of your books and pays a beneficiary on a corridor rail.

Typical sequence

Ensure a funded book

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

Pick corridor + beneficiary

Corridors → create or reuse a beneficiary.

Optional FX quote

Cross-currency sends: firm quote then pass quote_id.

Fee preview

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

Create

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

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.

Webhooks — event.payout.*
Transactions — unified history
API reference — Payouts

Getting started

Auth

Money

Errors

Webhooks

Typical sequence

Cancel

Purposes

Next

​Typical sequence

​Cancel

​Purposes

​Next

Typical sequence

Cancel

Purposes

Next