Skip to navigation

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 via POST /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

AuthorizationBearer
OAuth 2.0 access token issued by the CrissCross authorisation server.

Request

This endpoint expects an object.
merchantIdstringRequired
Merchant ID the payout is being made from.
merchantReferencestringRequired
Your reference for the payout. Used for idempotency and tracking.
destinationValueobjectRequired
paymentMethodIdenumRequired

Payment method to use. Valid values for payouts are: banktransfer, mobilemoney, cash, institutionwallet.

Allowed values:
paymentLocationstringRequired=3 characters

3-letter ISO country code (e.g. NGA).

senderobjectRequired

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.

attributesmap from strings to stringsOptional

Free-form key-value pairs attached to the payout.

payoutBeneficiaryIdstringOptional

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.

recipientobjectOptional

Recipient details. The type discriminator determines which fields are present. Provide either this field or payoutBeneficiaryId, not both.

supportingDocumentslist of stringsOptional

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

Payout transaction initiated successfully.
statusstring
Current payout status.
transactionIdstring
Unique identifier for the payout transaction.
messagestring

Human-readable status message.

merchantReferencestringOptional
Merchant reference from the original payout initiation.
sessionIdstringOptionalformat: "uuid"
Session ID associated with the payout, if applicable.
paymentMethodIdstringOptional

Payment method identifier (e.g. banktransfer, mobilemoney).

identifiersmap from strings to stringsOptional
Additional identifiers related to the payout.
paymentAttributesmap from strings to stringsOptional

Payout-specific attributes and metadata.

processorNamestringOptional

Name of the payout processor (if assigned).

processorReferencestringOptional

Processor-side reference for the payout (if available).

financialTransactionReferencestringOptional

Financial transaction reference returned by the processor (if available).

currentAttemptIdstringOptional
Identifier of the current delivery attempt.
batchPayoutIdstringOptional
Batch identifier, present when the payout is part of a batch.
authStateobjectOptional

Latest auth/state transition on the payout. The shape varies by state and (when present) authMethodType — additional method-specific fields may be present.

Errors

401
Unauthorized Error
422
Unprocessable Entity Error
500
Internal Server Error