Skip to navigation
PayoutsPayoutsPayouts

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. 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.

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. For example, KES payouts to Kenya also require 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.

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