Payouts API

Last updated: 2026-07-17

Use a public key for discovery and a secret key for payout creation. Monetary amounts are strings in minor units.

List payout banks

GET /merchant/api/v1/payouts/banks

Auth: Public key

Query parameter	Type	Presence	Meaning
countryCode	string	Required	ISO 3166-1 alpha-2 market country
paymentMethod	string	Required	Send PAYMENT_METHOD_BANK_ACCOUNT for bank discovery
trafficVertical	enum	Optional	Traffic category used by the payout
customerSegment	enum	Optional	Customer segment used by the payout

The response contains banks[] entries with code and name.

List payout mobile money operators

GET /merchant/api/v1/payouts/mmo

Auth: Public key

Query parameter	Type	Presence	Meaning
countryCode	string	Required	ISO 3166-1 alpha-2 market country
paymentMethod	string	Required	PAYMENT_METHOD_MOBILE_MONEY
trafficVertical	enum	Optional	Traffic category used by the payout
customerSegment	enum	Optional	Customer segment used by the payout

The response contains operators[] entries with operator and name. Display name; treat the public CAPS operator code as opaque and reuse it exactly as returned.

Create a payout

POST /merchant/api/v1/payouts/create

Auth: Secret key

Body field	Type	Presence	Meaning
amount	string (int64)	Required	Positive amount in minor units
currencyCode	string	Required	ISO 4217 currency
countryCode	string	Conditional	Selected payment-market country; required whenever the selected currency/method maps to more than one enabled country
paymentMethod	enum	Required	PAYMENT_METHOD_BANK_ACCOUNT, PAYMENT_METHOD_MOBILE_MONEY, or test method where supported
merchantReference	string	Required	Merchant-side payout reference
trafficVertical	enum	Optional	Preferred traffic category
customerSegment	enum	Optional	Customer segment

Add the detail block for the selected method:

Detail block	Fields
bankAccountDetails	bankCode and account required; name required for INR and ZAR; email conditional for INR
mobileMoneyDetails	mobileNumber required; operator required when the selected route is operator-aware; accountName conditional; email conditional for INR
testDetails	Non-production controls described in Test method controls

{
  "amount": "5000",
  "currencyCode": "GHS",
  "countryCode": "GH",
  "paymentMethod": "PAYMENT_METHOD_MOBILE_MONEY",
  "merchantReference": "PO-3002",
  "mobileMoneyDetails": {
    "operator": "<operator_from_discovery>",
    "mobileNumber": "<beneficiary_msisdn>"
  }
}

The response contains the created payment order. Reconcile its latest status; request acceptance is not a final payout outcome.

Outcomes

Discovery and creation can return INVALID_ARGUMENT for missing, malformed, or unavailable request values. A configured route that cannot accept the payout can return the public method_unavailable reason. Handle all non-success responses using Errors.

Related guide: Payouts.