Logo GenukaGenuka Pay
API Reference

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

Authenticated Payout Request
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE
Idempotency-Key: YOUR_UNIQUE_KEY   # optional, POST /payouts only

Endpoints

  • GET /api/v1/payouts
  • POST /api/v1/payouts
  • GET /api/v1/payouts/balance
  • GET /api/v1/payouts/{id}
  • POST /api/v1/payouts/{id}/cancel
  • POST /api/v1/payouts/{id}/retry

Create a Payout

Endpoint
POST /api/v1/payouts

Main Request Fields

ParameterTypeRequiredDescription
amountnumberYesPayout amount, minimum 1
currencystringYesXAF or XOF
countrystringNoRecipient country (two-letter ISO code)
payment_method_idstringConditionalOne of your company's payment methods
recipient_phonestringConditionalRecipient number in E.164 format, e.g. +237677001122. Required without payment_method_id.
operator_codestringConditionalRecipient's active operator. Required without payment_method_id.
recipient_first_namestringNoRecipient first name (100 characters max)
recipient_last_namestringNoRecipient last name (100 characters max)
external_idstringNoMerchant reference. Used as the idempotency key without Idempotency-Key.
descriptionstringNoBusiness context (255 characters max)
metadataobjectNoAdditional merchant metadata

You must provide either:

  • payment_method_id
  • or recipient_phone with operator_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

Create a Direct Payout
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

Endpoint
GET /api/v1/payouts

Parameters: 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

Endpoint
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

Endpoint
POST /api/v1/payouts/{id}/cancel

Only 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

Endpoint
POST /api/v1/payouts/{id}/retry

Sends 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

Endpoint
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

StatusDescription
AWAITING_APPROVALRequest received, waiting for Genuka Pay approval
PROCESSINGApproved, transfer in progress
SUCCESSFunds delivered to the recipient, balance debited
FAILEDFailed. Can be retried (back to awaiting approval).
CANCELLEDCancelled 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_id aligned with your ledger or payout batch identifiers
  • check available_balance before 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