Payouts

Prepare a payout

POST/v1/payouts

Creates a payout pending_approval and notifies every owner. There is no approval endpoint: an owner approves on the dashboard with an email code (PO-3). An API key is never treated as the maker for self-approval.

Parameters

Idempotency-Keystringin headerrequired: Unique per logical request, kept 24 hours. A retry with the same key and body replays the first response.

Body

beneficiary_idstring
phonestring
namestring
amountintegerrequired
reasonstringrequired
source_refstring

Responses

200Replay of an identical request within 24 h
201Payout prepared
400Invalid request
401Missing, invalid or revoked API key
403business_initiation_disabled
409idempotency_conflict
422no_healthy_connection, capability_unsupported or insufficient_refundable_balance
429More than 100 requests in this minute for this keyRetry-After
500Internal error

Error bodies and every code are listed under Errors; limits under Rate limits and Idempotency.

curl -X POST http://localhost:3000/api/v1/payouts \ -H "Authorization: Bearer $DCP_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"phone":"+254708374149","amount":125000,"reason":"reason"}'

{ "id": "mo_01JB8Q4Z2N5V7K3M9P6R0T1W8X", "object": "payout", "livemode": false, "status": "pending_approval", "amount": 125000, "currency": "KES", "beneficiary": { "id": "obj_01JB8Q4Z2N5V7K3M9P6R0T1W8X", "name": "name", "phone": "+254708374149" }, "reason": "reason", "source_ref": "source ref", "connection_id": "con_01JB8Q4Z2N5V7K3M9P6R0T1W8X", "provider_ref": "provider ref", "receiver_name": "receiver name", "failure_code": "failure code", "failure_message": "failure message", "attempts": [ { "attempt": 1, "channel": "api", "status": "pending", "provider_ref": "provider ref", "provider_code": "provider code", "provider_message": "provider message", "started_at": "2026-10-22T09:30:00.000Z", "finished_at": "2026-10-22T09:30:00.000Z" } ], "created_at": "2026-10-22T09:30:00.000Z", "completed_at": "2026-10-22T09:30:00.000Z" }