Payouts

A payout sends Kenyan shillings to one recipient, paid from your USDC balance. This page covers everything about them; the endpoint details are in the Payouts reference.

Destinations

Choose the destination by type. Your workspace may be limited to some types (limits.methods in GET /api/v1/account); others get METHOD_UNAVAILABLE.

// M-Pesa or Airtel Money wallet
{ "type": "mobile_money", "phone": "+254712345678", "network": "safaricom", "name": "Jane Wanjiku" }

// Till (Buy Goods)
{ "type": "till", "till_number": "5123456" }

// PayBill
{ "type": "paybill", "paybill_number": "247247", "account_number": "INV-2041" }

// Kenyan bank account (bank_code from GET /api/v1/banks)
{ "type": "bank", "bank_code": "KCBLKENX", "account_number": "1234567890", "account_name": "Jane Wanjiku" }

Amounts

• amount is what the recipient receives, in KES cents, as an integer: 150000 is KES 1,500.
• Whole shillings only: the amount must be a multiple of 100, or you get VALIDATION_ERROR.
• Fees are added on top. The total taken from your balance is debited_usdc on the payout.
• USDC amounts are decimal strings with 6 places ("11.948310"). Don't parse them into floats for accounting; use a decimal type.

Sending one

curl -X POST "https://api.autopayke.com/api/v1/payouts" \
  -H "Authorization: Bearer $AUTOPAYKE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "KES",
    "destination": { "type": "mobile_money", "phone": "+254700000001" },
    "reference": "order_1042"
  }'

What happens when you call it:

1. We check the Idempotency-Key, your key's scope and allowlist, and whether payouts are paused.
2. We validate the destination and check your per-payout, daily and monthly limits.
3. We price it at the current rate and check your balance covers the amount plus fees.
4. We take the total from your balance, record the payout and answer with it, status pending.
5. We send the money. Webhooks follow as it moves.

If any check fails, nothing is charged, you get an error code, and you can retry with the same Idempotency-Key.

Statuses

pending ──► processing ──► succeeded ──► reversed
   │             │
   │             ├──► in_review ──► processing / succeeded / failed
   │             │
   └─────────────┴──► failed

Treat succeeded as done for your customer, but keep listening: a reversal can arrive later. Mobile money usually completes in under a minute; banks can take longer, depending on the bank.

Why payouts fail

Quotes

POST /api/v1/payouts/quote takes the same body as a payout (minus reference, description and metadata) and returns the rate, fee_usdc, total_usdc and a fee_breakdown, after running the same destination and limit checks. It doesn't hold money or the rate; creating the payout prices it again, and the rate can move slightly in between. Quotes are free and don't count against limits.

Fees

You pay our cash-out fee less 0.5 percentage points (the API partner price) plus the Avalanche network fee. Depending on how fees are configured, the payout network's own charge is either inside our fee or shown separately as payout_cost_usdc. The quote and the payout always show exactly what you paid. See Fees and pricing for today's published rates.

References and metadata

Put your own id in reference (up to 64 characters) and anything else you'll want back in metadata (up to 20 string pairs). Both come back on the payout, its events and webhooks, and you can list payouts by reference. Don't store personal data you don't need, secrets or card numbers there.

Paying many people

There's no batch endpoint yet; send one payout per person from a queue. Give each its own Idempotency-Key derived from your batch and line (payroll-2026-11:line-42), keep under your requests-a-second limit, check your balance first with GET /api/v1/balance, and reconcile from webhooks.