Developers
HomeMerchantsDevelopers

Field Validation Reference

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 a 422 Unprocessable Entity error.

Payout Request Fields.

FieldRequiredFormat / TypeLength / RuleValidation Rule / Example Error
invoiceNumberOptionalAlphanumeric1–35 chars"Invoice Number must be between 1 and 35 characters"
beneficiaryType✅EnumACCOUNT, CARD, ORDER_REF, SAVED_CARD"Invalid beneficiaryType"
beneficiaryName✅Alphanumeric1–35 chars"Beneficiary Name must be between 1 and 35 characters"
beneficiaryAccountNumber✅*Alphanumeric1–34 chars"Beneficiary Account Number/IBAN must be between 1 and 34 characters"
beneficiaryBic✅*Alphanumeric8–11 chars"Beneficiary Swift/BIC/Route Code must be between 8 and 11 characters"
beneficiaryBankName✅*Alphanumeric1–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 42173-letter code"Invalid currency code"
beneficiaryCountry✅ISO 3166-1 alpha-22-letter code"Invalid country code"
beneficiaryAddressOptionalAlphanumeric1–70 chars"Beneficiary Address must be between 1 and 70 characters"
beneficiaryEmailOptionalEmailValid email format"Should be valid email pattern"
beneficiaryMobileNumberOptionalPhone numberValid mobile number"Invalid mobile number"
transactionAmount✅Decimal (2 places max)1–15 digits"Transaction Amount is mandatory"
transactionCurrency✅ISO 4217Must be AED"transactionCurrency must be AED"
transactionGroupOptionalAlphanumeric1–140 chars"Transaction Group must be between 1 and 140 characters"
transactionDescription✅Alphanumeric1–140 chars"Transaction Description must be between 1 and 140 characters"
transactionPurposeCode✅3-letter codeMust be valid (e.g. ACM, AES, CCP)"Invalid transaction purpose code"
ultimateSenderName✅Alphanumeric1–140 chars"Ultimate Sender Name must be between 1 and 140 characters"
ultimateSenderAddress✅Alphanumeric1–70 chars"Ultimate Sender Address must be between 1 and 70 characters"
ultimateSenderCountry✅ISO 3166-1 alpha-2Must be AE"ultimateSenderCountry must be AE"
ultimateSenderPostCode✅AlphanumericUp to 16 chars"Invalid post code"
ultimateSenderAddressType✅EnumHOME, BIZZ"Invalid address type"

📘

The following fields are conditionally required based on beneficiaryType:

  • beneficiaryAccountNumber, beneficiaryBic, beneficiaryBankName → required if beneficiaryType is ACCOUNT
  • beneficiaryAccountNumber → required if beneficiaryType is CARD
  • orderRef, outletRef → required if beneficiaryType is ORDER_REF
  • beneficiaryCardTokenRef, outletRef → required if beneficiaryType is SAVED_CARD
  • transactionPurposeCode must be CCP if beneficiaryType is CARD, ORDER_REF, or SAVED_CARD

Related Resources