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/{id}

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

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 for direct payout
`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

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_CM",
    "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. Not every payout will still be cancellable when your request arrives.

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.

Create Payouts

Recipient Flexibility

Operational Tracking

On this page