This guide lists all the required fields for initiating a Payout via API, including their validation constraints and related error messages.
All fields listed below are mandatory unless stated otherwise. Submitting invalid data will result in a422 Unprocessable Entityerror.
Payout Request Fields.
| Field | Required | Format / Type | Length / Rule | Validation Rule / Example Error |
|---|---|---|---|---|
invoiceNumber | Optional | Alphanumeric | 1–35 chars | "Invoice Number must be between 1 and 35 characters" |
beneficiaryType | ✅ | Enum | ACCOUNT, CARD, ORDER_REF, SAVED_CARD | "Invalid beneficiaryType" |
beneficiaryName | ✅ | Alphanumeric | 1–35 chars | "Beneficiary Name must be between 1 and 35 characters" |
beneficiaryAccountNumber | ✅* | Alphanumeric | 1–34 chars | "Beneficiary Account Number/IBAN must be between 1 and 34 characters" |
beneficiaryBic | ✅* | Alphanumeric | 8–11 chars | "Beneficiary Swift/BIC/Route Code must be between 8 and 11 characters" |
beneficiaryBankName | ✅* | Alphanumeric | 1–35 chars | "Beneficiary Bank Name must be between 1 and 35 characters" |
orderRef | ✅* | Alphanumeric | — | "orderRef is required for beneficiaryType ORDER_REF" |
beneficiaryCardTokenRef | ✅* | Alphanumeric | — | "beneficiaryCardTokenRef is required for beneficiaryType SAVED_CARD" |
outletRef | ✅* | Alphanumeric | — | "outletRef is required for ORDER_REF or SAVED_CARD" |
beneficiaryAccountCurrency | ✅ | ISO 4217 | 3-letter code | "Invalid currency code" |
beneficiaryCountry | ✅ | ISO 3166-1 alpha-2 | 2-letter code | "Invalid country code" |
beneficiaryAddress | Optional | Alphanumeric | 1–70 chars | "Beneficiary Address must be between 1 and 70 characters" |
beneficiaryEmail | Optional | Valid email format | "Should be valid email pattern" | |
beneficiaryMobileNumber | Optional | Phone number | Valid mobile number | "Invalid mobile number" |
transactionAmount | ✅ | Decimal (2 places max) | 1–15 digits | "Transaction Amount is mandatory" |
transactionCurrency | ✅ | ISO 4217 | Must be AED | "transactionCurrency must be AED" |
transactionGroup | Optional | Alphanumeric | 1–140 chars | "Transaction Group must be between 1 and 140 characters" |
transactionDescription | ✅ | Alphanumeric | 1–140 chars | "Transaction Description must be between 1 and 140 characters" |
transactionPurposeCode | ✅ | 3-letter code | Must be valid (e.g. ACM, AES, CCP) | "Invalid transaction purpose code" |
ultimateSenderName | ✅ | Alphanumeric | 1–140 chars | "Ultimate Sender Name must be between 1 and 140 characters" |
ultimateSenderAddress | ✅ | Alphanumeric | 1–70 chars | "Ultimate Sender Address must be between 1 and 70 characters" |
ultimateSenderCountry | ✅ | ISO 3166-1 alpha-2 | Must be AE | "ultimateSenderCountry must be AE" |
ultimateSenderPostCode | ✅ | Alphanumeric | Up to 16 chars | "Invalid post code" |
ultimateSenderAddressType | ✅ | Enum | HOME, BIZZ | "Invalid address type" |
The following fields are conditionally required based onbeneficiaryType:
beneficiaryAccountNumber,beneficiaryBic,beneficiaryBankName→ required ifbeneficiaryTypeisACCOUNTbeneficiaryAccountNumber→ required ifbeneficiaryTypeisCARDorderRef,outletRef→ required ifbeneficiaryTypeisORDER_REFbeneficiaryCardTokenRef,outletRef→ required ifbeneficiaryTypeisSAVED_CARDtransactionPurposeCodemust beCCPifbeneficiaryTypeisCARD,ORDER_REF, orSAVED_CARD
Related Resources
- Payouts Overview
- Sample Request & Response ← (Link to Postman or API reference once live)
- Transaction Purpose Codes