Payouts API

Initiate disbursements, inspect payout state, and manage recipient payout flows.

Introduction

Use payouts when your product needs to disburse funds 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

Inspect the current payout state and react to downstream provider changes.

Required Headers

Authenticated Payout Request

X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

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

Parameter	Type	Required	Description
`amount`	`number`	Yes	Payout amount
`currency`	`string`	Yes	ISO currency code
`country`	`string`	No	Recipient country
`payment_method_id`	`string`	Conditional	Existing saved payout method
`recipient_phone`	`string`	Conditional	Recipient number in E.164 format, e.g. `+237677001122`
`operator_code`	`string`	Conditional	Recipient operator for direct payout
`recipient_first_name`	`string`	No	Recipient first name
`recipient_last_name`	`string`	No	Recipient last name
`external_id`	`string`	No	Merchant reference
`description`	`string`	No	Business context
`metadata`	`object`	No	Additional merchant metadata

You must provide either:

payment_method_id

or recipient_phone with operator_code

Valid operator codes are listed in Countries and operators. An unknown or inactive operator_code is rejected with a 422.

Example Request

Create a Direct Payout

curl -X POST "{{BASE_URL}}/api/v1/payouts" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -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"
  }'

Retrieve a Payout

Endpoint

GET /api/v1/payouts/{id}

Use this endpoint to inspect the latest known payout state after initiation.

Cancel a Payout

Endpoint

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

Cancellation depends on both current internal state and downstream provider state.

Operational Guidance

save recipient methods when you need recurring disbursement flows

keep external_id aligned with your ledger or payout batch identifiers

consume payout webhooks for final state synchronization

separate business refusal handling from transient provider failures

Production recommendation

Treat payouts as asynchronous operations. Use direct request responses for immediate UX feedback, but use event delivery and later reconciliation for final accounting.

Retry a Payout

Endpoint

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

Retries a failed payout without creating a new transaction.

Available Balance

Endpoint

GET /api/v1/payouts/balance

Your settlement account's payable balance, in the corridor's currency.

Statuses

Status	Description
`AWAITING_APPROVAL`	Waiting for approval before execution
`INITIATED`	Approved, not yet sent to the operator
`PROCESSING`	Sent, being processed
`SUCCESS`	Funds delivered to the recipient
`FAILED`	Failed. Can be retried.
`EXPIRED`	No operator response within the allowed window
`CANCELLED`	Cancelled before execution

Payout minimums vary by operator — read min_payout_amount from the coverage endpoint rather than hard-coding them.

Create Payouts

Recipient Flexibility

Operational Tracking

On this page