Payouts
Send money to a customer. Request and response shapes mirror payments.
Initiate a payout.
{
"method": "mobile_money_mtn",
"country": "CG",
"amount": { "value": "5000", "currency": "XAF" },
"reference": "REFUND-456",
"idempotency_key": "b5e4d3c2-0000-0000-0000-000000000000",
"customer": { "phone": "242064661331" },
"metadata": { "refund_for": "ORDER-123" }
}Returns 202 Accepted with the same object shape as a payment.
Payout fields#
| Field | Required | Description |
|---|---|---|
method | Yes | Payout method code (from /payment-methods) |
country | For country-scoped methods | ISO 3166-1 alpha-2 country code |
amount.value | Yes | Amount to send, as a minor-units string |
amount.currency | Yes | ISO-4217 currency code |
idempotency_key | Yes | A unique UUID for this payout |
customer | Yes | Recipient details, e.g. phone for mobile money |
reference | No | Your own payout reference |
metadata | No | Any key/value pairs, echoed back on webhooks |
Payment-only fields. description, charge and tax are payment fields. They describe a checkout and have no meaning on a payout, so they are not sent.
Effect on your balance#
Submitting a payout reserves the amount against your wallet's available balance immediately, before it settles. Your available balance drops at submission, not at success, so a batch of payouts draws available down as each is submitted. If a payout fails, the reserved amount returns to available.
Get a payout's status#
A payout settles to success or failed.
Payouts cannot expire. Expiry applies only to a payment, where the customer must approve the prompt on their handset in time. A payout is a push to the customer's wallet with no approval step, so it has no expired state. It ends in success or failed only.
curl "{BASE_URL}/payouts/b5e4d3c2-0000-0000-0000-000000000000" \
-H "X-Api-Key: <your-api-key>"List payouts#
Filterable list of your payouts.
The same filters apply as for payments: status, method, from_date, to_date, limit (max 200), offset. The response uses the same page wrapper (items, total, limit, offset) described under Payments.
Fund the wallet first. A payout draws on the available balance of the wallet in that currency. Check your balance before releasing a batch of payouts.
Maly Tech Ltd. This guide is provided for information. Where it differs from your signed agreement, the agreement applies.