Initiate a payout transaction

Creates a new payout transaction for the specified recipient

Request

This endpoint expects an object.

merchantIdstringRequired

Merchant ID for the payout

merchantReferencestringRequiredformat: "^[A-Za-z0-9 .,/:()+'?-]+$"1-100 characters

Merchant reference for the payout. Letters, digits, spaces and . , / : ( ) + ’ ? - only; max 100 characters.

destinationValueobjectRequired

Destination amount and currency for the payout

paymentMethodIdenumRequired

Payment method identifier (e.g., “banktransfer”)

paymentLocationstringRequired

3-letter ISO country code

senderobjectRequired

Sender details for the payout (required for KYT screening)

supportingDocumentslist of stringsOptional

Base64-encoded supporting documents (PDF or image), max 5 of ~3MB each. Required by some high-value rails, e.g. Kenya RTGS payouts of KES 1,000,000 or more.

attributesmap from strings to stringsOptional

Additional payout attributes as key-value pairs

recipientobjectOptional

Recipient details for the payout. Mutually exclusive with payoutBeneficiaryId.

payoutBeneficiaryIdstringOptionalformat: "uuid"

Reference to a pre-validated PayoutBeneficiary. Mutually exclusive with recipient.

Response

Payout transaction initiated successfully

Errors

401

Unauthorized Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error

$	curl -X POST https://api.payos.money/api/v1/payout/initiate \
>	-H "Content-Type: application/json" \
>	-d '{
>	"merchantId": "string",
>	"merchantReference": "string",
>	"destinationValue": {
>	"minorAmount": 1,
>	"currency": "string"
>	},
>	"paymentMethodId": "card",
>	"paymentLocation": "string",
>	"sender": {
>	"fullName": "string",
>	"identity": "passport",
>	"identityNumber": "string"
>	}
>	}'