Payouts

A payout sends funds from the merchant balance to a mobile money or bank destination.

Current implemented route family: api/v1/payouts

The Payout object

{
  "id": "po_abc123",
  "object": "payout",
  "amount": 50000,
  "currency": "XOF",
  "status": "in_transit",
  "destination": {
    "type": "mobile_money",
    "country": "SN",
    "operator": "orange_money",
    "msisdn": "+221770000000"
  },
  "arrival_date_estimate": "2026-06-04T12:10:00Z",
  "expected_by": "2026-06-04T12:10:00Z",
  "delay_state": null,
  "delay_reason": null,
  "delayed_at": null,
  "metadata": {
    "batch_id": "batch_123",
    "supplier_id": "sup_456"
  },
  "failure_code": null,
  "failure_message": null
}

Field	Type	Description
id	string	Public payout ID.
object	string	Always payout.
amount	integer:int64	Amount in the smallest currency unit.
currency	string	Payout currency.
status	string	Current status: pending, in_transit, paid, failed, or canceled.
destination	object	Normalized payout destination.
arrival_date_estimate	string:date-time	Legacy arrival estimate.
expected_by	string:date-time	Estimated completion time. For mobile money, the default is creation time + 10 minutes.
delay_state	string	delayed when the payout is delayed, otherwise null.
delay_reason	string	Delay reason: operator_pending, operator_timeout, operator_down, or unknown.
delayed_at	string:date-time	Time when the delay was detected.
metadata	object<string,string>	Metadata attached to the payout.
failure_code	string	Failure code when status is failed.
failure_message	string	Human-readable failure message when available.

Create a Payout

POST /api/v1/payouts

Authentication:

• ApiKey or AppToken
• payouts.write scope
• environment header required
• Idempotency-Key required in live

Parameter	Type	Required	Description
amount	integer:int64	Yes	Amount in the smallest currency unit. Must be strictly positive.
currency	string	Yes	Three-letter ISO currency code, for example XOF.
destination	object	Conditional	Inline destination. Required when payout_method_id is not provided.
payout_method_id	string:uuid	Conditional	Saved payout destination. Required when destination is not provided.
metadata	object<string,string>	No	Business metadata. Keys and values must be strings.

You must provide one usable destination: either destination or payout_method_id. If no destination is provided, the API returns an invalid destination error.

Inline Mobile Money Destination

Parameter	Type	Required	Description
destination.type	string	Yes	mobile_money.
destination.currency	string	No	Destination currency. If omitted, currency is used.
destination.country	string	Yes	ISO 3166-1 alpha-2 country code.
destination.operator	string	Yes	Mobile money operator. The country + operator pair is validated against the operator catalog.
destination.msisdn	string	Yes	Beneficiary mobile money number in international format.

{
  "amount": 50000,
  "currency": "XOF",
  "destination": {
    "type": "mobile_money",
    "country": "SN",
    "operator": "orange_money",
    "msisdn": "+221770000000"
  },
  "metadata": {
    "batch_id": "batch_123",
    "supplier_id": "sup_456"
  }
}

Inline Bank Destination

Parameter	Type	Required	Description
destination.type	string	Yes	bank.
destination.currency	string	No	Destination currency. If omitted, currency is used.
destination.bank_code	string	Yes	Bank code or routing code.
destination.account_number	string	Yes	Bank account number.
destination.account_name	string	Yes	Account holder name.

{
  "amount": 125000,
  "currency": "XOF",
  "destination": {
    "type": "bank",
    "bank_code": "BANKSNDA",
    "account_number": "SN1234567890",
    "account_name": "Supplier SARL"
  },
  "metadata": {
    "invoice_id": "inv_789"
  }
}

Saved Destination

Use payout_method_id when a destination has already been saved and activated for the merchant.

{
  "amount": 50000,
  "currency": "XOF",
  "payout_method_id": "9b9d7f48-1e63-4f4f-a6dd-9b85f5cc6c8a",
  "metadata": {
    "batch_id": "batch_123"
  }
}

The saved destination must belong to the merchant, be active, and not still be blocked by a safety delay.

Metadata

metadata is an object<string,string> for business references such as batch_id, supplier_id, invoice_id, payroll_run_id, or source_system.

When payouts are executed through the payout engine, the platform adds or replaces the source and environment keys. Avoid using those two keys for business values that must remain unchanged.

Retrieve a Payout

GET /api/v1/payouts/{id}

Authentication:

• ApiKey or AppToken
• payouts.read scope
• environment header required

Parameter	Type	Required	Description
id	string	Yes	Public payout ID.

Execution Rules

• The amount must be positive.
• Currency is required.
• In live, Idempotency-Key is required to prevent duplicate disbursements.
• The merchant available balance must cover the amount and estimated fees.
• Mobile money payouts validate the country + operator pair and operator eligibility for the payout direction.
• Inline bank destinations are supported in sandbox through the payout engine and may follow a legacy path depending on the environment.

Related Merchant Routes

Merchant operational routes are available under:

• GET /api/v1/merchant/payouts
• GET /api/v1/merchant/payouts/{id}
• POST /api/v1/merchant/payouts
• GET /api/v1/merchant/settings/payouts
• PATCH /api/v1/merchant/settings/payouts
• POST /api/v1/merchant/settings/payouts/destinations
• DELETE /api/v1/merchant/settings/payouts/destinations/{id}

Legacy-compatible merchant paths may also be available under api/merchant/*.

Integration Note

The current public surface only exposes payout creation and retrieval. Do not document payout cancellation or public payout listing until those endpoints appear in the generated API reference.