Initiate Payout
Initiates a new payout transaction. The destination can be specified in one of two ways:
- Inline
recipient— supply the recipient’s account details directly on this request. Validation happens at payout time. Best for one-off payouts. payoutBeneficiaryId— reference a pre-validated Payout Beneficiary you previously registered viaPOST /payout-beneficiaries. The beneficiary’s destination is validated once up front, then reused on every subsequent payout.
Exactly one of recipient or payoutBeneficiaryId must be provided — they are mutually exclusive.
Some fields are required only in specific destination markets. Get Payout Field Requirements returns the fields your account needs for a corridor and amount. See Supported Destinations for a per-market summary of when extra fields (in particular on the sender object) apply, and follow the linked per-market guide — for example Kenya or Egypt — for the full field list and worked examples.
Some high-value payouts need supporting documents. Bank transfers to Kenya of KES 1,000,000 or more settle over RTGS and need supportingDocuments and sender.senderAddress. See Kenya.
The response contains the payout’s initial state and is the same shape returned by Retrieve Payout and emitted on payout webhooks.
Authentication
Request
Payment method to use. Valid values for payouts are:
banktransfer, mobilemoney, cash, institutionwallet.
3-letter ISO country code (e.g. NGA).
Sender details for the payout. fullName, identity, and identityNumber are required on every request for KYT/KYC screening.
Additional sender fields are required in specific destination markets, depending on the provider that carries the payout. Get Payout Field Requirements returns the exact list for your account. For example, some Kenya mobile wallet providers need purposeOfFunds, sourceOfFunds and relationship. See the Kenya guide. XAF payouts to Cameroon require phoneNumber, country, sourceOfFunds and gender; XOF payouts to Togo T-Money (operator: "togocell") require phoneNumber and country — see Central Africa and West Africa. Supported Destinations has a per-market summary of when the sender object carries extra requirements.
Free-form key-value pairs attached to the payout.
Identifier of a pre-validated PayoutBeneficiary to send funds to.
Use this instead of supplying recipient inline. Exactly one of payoutBeneficiaryId
or recipient must be provided — they are mutually exclusive.
The referenced beneficiary must be in status: approved. Requests that reference a
pending_review, rejected, or failed beneficiary are rejected with 422.
Recipient details. The type discriminator determines which fields are present.
Provide either this field or payoutBeneficiaryId, not both.
Base64-encoded documents that support the payout, such as an invoice or a contract. Use standard base64 with no data: prefix. Each document must be a PDF, PNG or JPEG file of at most ~3MB once decoded.
Required for bank transfers to Kenya of KES 1,000,000 or more, which settle over RTGS. Request validation does not check for it: a payout sent without one fails before any funds move. Only the first document is sent to the bank. See Kenya.
Response
Human-readable status message.
Payment method identifier (e.g. banktransfer, mobilemoney).
Payout-specific attributes and metadata.
Name of the payout processor (if assigned).
Processor-side reference for the payout (if available).
Financial transaction reference returned by the processor (if available).
Latest auth/state transition on the payout. The shape varies by state and (when present)
authMethodType — additional method-specific fields may be present.