Send a disbursement

POST/v1/disburseDisburse

Sends money from your TchokoPay balance to any mobile money number.

What the payment is for is yours to decide — a seller settlement, a user withdrawal, a loan disbursement, a refund. The API does not model it.

This is not a withdrawal. A withdrawal moves your balance to your own account and happens in the dashboard. This pays a third party and cannot be undone once the network has it.

Requires a key with the Disburse permission. See Scopes.

Request

curl -X POST https://connect.tchokopay.com/v1/disburse \
  -H "Authorization: Bearer tchoko_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-4417-attempt-1" \
  -d '{
    "amount": 25000,
    "currency": "XAF",
    "phone": "670000000",
    "recipientName": "Amina Njoya",
    "provider": "mtn_cm",
    "merchantReference": "supplier-invoice-4417"
  }'

Body parameters

Field	Type	Required	Description
`amount`	number	required	How much to send, in `currency`. Must be within your payout limits and your available balance.
`currency`	string	required	A currency you hold a balance in. No conversion happens — you pay out what you hold.
`phone`	string	required	The mobile money number to pay, in local format. Max 32 characters.
`recipientName`	string	optional	Who is being paid. Shown on your dashboard and to our reviewers. Max 120 characters.
`provider`	string	optional	Which network — `mtn_cm`, `orange_cm`. Omit and we detect it from the number. Supply it when you already know, so a mis-detected network can't send money to the wrong operator.
`country`	string	optional	ISO country of the recipient number. Defaults to `CM`.
`merchantReference`	string	optional	Your own identifier. Echoed back as `merchantReference` on every response and webhook. Max 120 characters.

Headers

Header	Required	Description
`Authorization`	required	`Bearer tchoko_live_...` on a key with the Disburse permission.
`Content-Type`	required	`application/json`
`Idempotency-Key`	required	Any string you choose, max 200 characters.

Idempotency-Key is required here, unlike on payments. A duplicated charge creates an invoice nobody has to pay; a duplicated payout sends real money twice and cannot be recalled. Send the same key again and you get the same payout back, never a second one.

Response

201 Created

{
  "reference": "PO-1787962449863-7B361B",
  "status": "PENDING",
  "amount": 25000,
  "currency": "XAF",
  "phone": "670000000",
  "recipientName": "Amina Njoya",
  "merchantReference": "payout_4417",
  "providerReference": null,
  "awaitingReview": true,
  "statusReason": "Above the 20000 review threshold — held for approval rather than dispatched automatically.",
  "createdAt": "2026-08-29T01:34:09.863Z"
}

Field	Description
`reference`	TchokoPay's reference for this payout. Use it to check status later.
`status`	`PENDING` right after creation — see Payout status.
`awaitingReview`	`true` when the amount tripped your review threshold and a person has to release it. Your money is reserved either way.
`merchantReference`	Echoes back the `reference` you sent, or `null`.
`providerReference`	The network's own transaction id, once we have one.
`statusReason`	Why it's being held, or why it failed. `null` when neither applies.

Errors

Status	Meaning
`400`	No `Idempotency-Key`, unknown currency, non-positive amount, or not enough balance — the message tells you what you have and what was needed. Also returned when payouts aren't enabled on the platform.
`401`	Missing, invalid, or revoked API key.
`403`	Your key doesn't have the Disburse permission, payouts are off for the platform or your account, or the amount is over one of your limits. The message says which.
`429`	Rate limit hit — see Errors & rate limits.

Request

Body parameters

Headers

Response

Errors

What happens next

Your balance is reserved

It goes to the network, or waits

You find out

On this page