Payouts API
Request a disbursement to a saved method or to a number supplied inline, then follow its approval.
Introduction
Use payouts when your product needs to disburse funds from your balance to users, suppliers, merchants, or operational partners.
Create Payouts
Send money using either a saved payment method or direct recipient details.
Recipient Flexibility
Support both recurring recipients and one-off disbursement flows.
Operational Tracking
Follow each payout from approval to completion, and check your available balance.
Every payout is approved by hand
A payout created through the API or the dashboard starts in AWAITING_APPROVAL. The Genuka Pay team approves it, carries out the transfer, then marks it as successful. Your balance is only debited at that point. Expect a delay between the request and the funds arriving, and do not present a payout as "sent" when it is created.
Required Headers
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE
Idempotency-Key: YOUR_UNIQUE_KEY # optional, POST /payouts onlyEndpoints
GET /api/v1/payoutsPOST /api/v1/payoutsGET /api/v1/payouts/balanceGET /api/v1/payouts/{id}POST /api/v1/payouts/{id}/cancelPOST /api/v1/payouts/{id}/retry
Create a Payout
POST /api/v1/payoutsMain Request Fields
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Payout amount, minimum 1 |
currency | string | Yes | XAF or XOF |
country | string | No | Recipient country (two-letter ISO code) |
payment_method_id | string | Conditional | One of your company's payment methods |
recipient_phone | string | Conditional | Recipient number in E.164 format, e.g. +237677001122. Required without payment_method_id. |
operator_code | string | Conditional | Recipient's active operator. Required without payment_method_id. |
recipient_first_name | string | No | Recipient first name (100 characters max) |
recipient_last_name | string | No | Recipient last name (100 characters max) |
external_id | string | No | Merchant reference. Used as the idempotency key without Idempotency-Key. |
description | string | No | Business context (255 characters max) |
metadata | object | No | Additional merchant metadata |
You must provide either:
payment_method_id- or
recipient_phonewithoperator_code
There is no "default" method: without payment_method_id, the recipient must be described in the request.
Valid operator codes are listed in Countries and operators. An unknown or inactive operator_code is rejected with a 422. An amount above your available balance (balance minus payouts already pending) is refused.
Example Request
curl -X POST "https://api-pay.genuka.com/api/v1/payouts" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Idempotency-Key: payout_9001" \
-H "Content-Type: application/json" \
-d '{
"amount": 25000,
"currency": "XAF",
"recipient_phone": "+237677001122",
"operator_code": "MTN_MOMO",
"recipient_first_name": "Jean",
"recipient_last_name": "Mballa",
"external_id": "payout_9001",
"description": "Vendor settlement"
}'Response
HTTP 202:
{
"data": {
"id": "01k7c4t9m2y8x5b3n6q0r1s2t3",
"reference": "01k7c4t9m3...",
"track_id": "PX-01k7c4t9m2y8x5b3n6q0r1s2t4",
"idempotency_key": "payout_9001",
"amount": 25000,
"currency": "XAF",
"provider_fee_amount": null,
"genuka_fee_amount": null,
"total_fee_amount": null,
"net_amount": null,
"status": "AWAITING_APPROVAL",
"type": "PAYOUT",
"recipient_phone": "+237677001122",
"recipient_name": "Jean Mballa",
"operator_code": "MTN_MOMO",
"failure": null,
"rejection_reason": null,
"created_at": "2026-09-19T10:00:00.000000Z",
"completed_at": null,
"fee_breakdown": { "...": "..." }
}
}A request replayed with the same idempotency key returns the existing payout instead of creating a second one.
List Payouts
GET /api/v1/payoutsParameters: per_page, filter[status], filter[from] and filter[to] (dates), filter[phone] (recipient number, partial match), sort (created_at, amount, status, reference, - prefix for descending; -created_at by default).
Retrieve a Payout
GET /api/v1/payouts/{id}{id} is the payout id (not its track_id). Add ?sync=1 to ask for a status resync before the response.
Cancel a Payout
POST /api/v1/payouts/{id}/cancelOnly a payout still awaiting approval (AWAITING_APPROVAL) can be cancelled. Once approved, the disbursement may already be under way, so cancellation is refused with a 400 error. Cancelling a payout that is already cancelled or failed changes nothing.
Retry a Payout
POST /api/v1/payouts/{id}/retrySends a failed payout (FAILED) back to awaiting approval (AWAITING_APPROVAL), without creating a new transaction. It goes through approval again, and your available balance is checked again: the retry is refused if it no longer covers the amount.
Available Balance
GET /api/v1/payouts/balance{
"data": {
"current_balance": 150000,
"pending_payouts_amount": 25000,
"available_balance": 125000,
"currency": "XAF",
"environment": "LIVE",
"settlement_account_id": "01k5...",
"can_payout": true
}
}available_balance is what you can still request: the balance minus pending payouts, which are only debited when executed. can_payout is false until a settlement account exists for this environment. The response also carries country, your company's country.
Statuses
| Status | Description |
|---|---|
AWAITING_APPROVAL | Request received, waiting for Genuka Pay approval |
PROCESSING | Approved, transfer in progress |
SUCCESS | Funds delivered to the recipient, balance debited |
FAILED | Failed. Can be retried (back to awaiting approval). |
CANCELLED | Cancelled by you, or refused during approval — rejection_reason then says why |
Tracking a Payout
Payout status changes currently fire no webhook: the payout.* events can be selected on an endpoint but are not emitted yet. Read the payout back with GET /api/v1/payouts/{id} to follow its progress.
Operational Guidance
- save recipient methods when you need recurring disbursement flows
- keep
external_idaligned with your ledger or payout batch identifiers - check
available_balancebefore requesting a payout - separate business refusal handling from transient failures
Payout minimums vary by operator — read min_payout_amount from the coverage endpoint rather than hard-coding them.
How is this guide?
Last updated on