Payouts API

Last updated: 2026-09-25

Use a public key for discovery and a secret key for payout creation. Monetary amounts use minor units and must follow the amount representation rules.

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 classification for this request; an explicit supported value takes precedence over the account default
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 classification for this request; an explicit supported value takes precedence over the account default
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	Required	ISO 3166-1 alpha-2 country code of the selected payment market; it is never inferred from currency or payment method
paymentMethod	enum	Required	PAYMENT_METHOD_BANK_ACCOUNT or PAYMENT_METHOD_MOBILE_MONEY
merchantReference	string	Required	Merchant-side payout reference and idempotency key
trafficVertical	enum	Optional	Traffic classification for this request; an explicit supported value takes precedence over the account default
customerSegment	enum	Optional	Customer segment

Add the detail block for the selected method:

Detail block	Fields
bankAccountDetails	bankCode and account required; supply name unless omission is explicitly supported for your configured payout path; email conditional for INR
mobileMoneyDetails	mobileNumber required; operator required when the selected route is operator-aware; supply accountName unless omission is explicitly supported for your configured payout path; email conditional for INR

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

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

You can safely retry an equivalent create request with the same merchantReference; the API returns the existing payout. A request that reuses the reference with different data is rejected, so use a new reference for each distinct intended payout.

Outcomes

Discovery and creation can return INVALID_ARGUMENT for missing, malformed, or unsupported request values. A configured method can return the public method_unavailable reason.

For the account-level HTTP 400 / FAILED_PRECONDITION response with violation type merchant_payout_accounting_not_ready, contact support before retrying. See Payout unavailable for the account.

For HTTP 503 / UNAVAILABLE with the documented operation_busy preparation response, wait for google.rpc.RetryInfo.retryDelay and retry an equivalent request with the same merchantReference. See Payout preparation temporarily unavailable for the distinction from an unknown transport outcome. The JSON retry details are sufficient; an HTTP Retry-After header is not required.

Related guide: Payouts.