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](#tag/PayoutBeneficiaries) 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. The response contains the payout's initial state and is the same shape returned by [Retrieve Payout](#operation/getPayout) 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.

paymentLocationstringRequired=3 characters

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

senderobjectRequired

Sender details for the payout. fullName, identity, and identityNumber are required for KYT/KYC screening; the remaining fields are optional but may be required by certain destinations.

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.

merchantReferencestring
Merchant reference from the original payout initiation.
sessionIdstringformat: "uuid"
Session ID associated with the payout, if applicable.
paymentMethodIdstring

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

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

Payout-specific attributes and metadata.

processorNamestring

Name of the payout processor (if assigned).

processorReferencestring

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

financialTransactionReferencestring

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

currentAttemptIdstring
Identifier of the current delivery attempt.
batchPayoutIdstring
Batch identifier, present when the payout is part of a batch.
authStateobject

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