Payout Validation Rules

Payee Basic Information Validation Details 👤

When creating or updating a payee, the system enforces a strict PayeeValidator check. If the validation fails, a code: 100001 will be returned.

Field	Required	Length Limit	Character Set & Regex Requirements	Failure Prompt (code: 100001)
`firstName`	No	≤35	ASCII letters and spaces only (`^[a-zA-Z\s]*$`)	First name must not exceed 35 characters First name contains invalid characters
`lastName`	Yes	≤35	ASCII letters and spaces only (`^[a-zA-Z\s]+$`)	Please enter last name or company name Last name must not exceed 35 characters Last name or company name contains invalid characters
`bankName`	Yes	≤35	ASCII letters/numbers; boundaries must be alphanumeric; spaces and `- ' & . , ( ) /` allowed in the middle	Please enter bank name Bank name must not exceed 35 characters Bank name contains invalid characters
`bankCode`	Required if `receiveType=local`	≤20	Half-width letters or numbers only (`^[a-zA-Z0-9]+$`)	Please enter routing number Bank code must not exceed 20 characters Bank code only supports half-width letters or numbers
`bicSwift`	Required if `receiveType=swift`	8 or 11	Half-width letters or numbers only (`^[a-zA-Z0-9]+$`)	Please enter SWIFT/BIC code SWIFT/BIC code format error... SWIFT/BIC code only supports half-width letters or numbers
`accountNumber`	Yes	≤35	ASCII letters, numbers, spaces, and hyphens `-` only (`^[A-Za-z0-9\s\-]+$`)	Please enter bank account number Account number must not exceed 35 characters Account number only supports letters, numbers, spaces, and hyphens

Payee Address Information Validation Details 🏠

Address fields (payeeAddress and bankAddress) only trigger validation when provided. These rules are constrained by both the strict PayeeValidator and the broader DTO pipeline checks; the stricter constraint always applies.

Field	Required	Length Limit (Strict/Broad)	Character Set & Regex Requirements	Failure Prompt (Strict check code: 100001)
`line1`	Yes	≤70 (Strict) / ≤255 (Broad)	Unicode letters/numbers, spaces, and `.,'#-/&()`	Please enter detailed address Address line1 must not exceed 70 characters Address line1 only supports letters, numbers, and common punctuation
`line2`	No	≤35 (Strict) / ≤255 (Broad)	Unicode letters/numbers, spaces, and `.,'#-/&()`	Address line2 must not exceed 35 characters Address line2 only supports letters, numbers, and common punctuation
`postCode`	Yes	≤16 (Strict) / ≤50 (Broad)	ASCII letters, numbers, spaces, and hyphens `-` only	Please enter postal code Postal code must not exceed 16 characters Postal code contains invalid characters
`city`	Yes	≤35 (Strict) / Required (Broad)	Unicode letters/numbers, spaces, and `.,'-`	Please enter city name City name must not exceed 35 characters City name contains invalid characters
`state`	Yes	≤35 (Strict) / Required (Broad)	Unicode letters/numbers, spaces, and `.,'-`	Please enter state/province name State/province name must not exceed 35 characters State/province name contains invalid characters
`country`	Yes	Strictly 2 chars	Must be a 2-character ISO code (Restricted by DTO `@Length(2, 2)`)	(Intercepted by DTO pipeline, returns 999901 with i18n prompt)

Payout Submission Pre-validation Rules (va_005 Exclusive) 🚀

When the payout channel resolves to va_005, the system executes 20 granular field-level checks that exactly match the actual downstream submission requirements. Any validation failure here directly returns code: 100001 along with the original English message from the channel.

📘
Character Set and Boundary Normalization Logic
SWIFT Character Set: Requires alphanumeric characters at the boundaries, while allowing letters, numbers, spaces, and specific symbols (/ - ? : ( ) . , ' +) in the middle.
Boundary Rules: All rules involving "alphanumeric boundaries" enforce the validateAlphanumericBoundary check under the hood.
Normalization Processing: Before constructing the payload, the system automatically normalizes Unicode whitespace to half-width spaces, transliterates Chinese characters to Pinyin, and trims invalid characters at the boundaries to minimize false rejections. Names, bank names, account numbers, and postal codes are excluded from Pinyin transliteration.

Target Field	Source Field or Logical Mapping	Core Validation Constraints
COUNTERPARTY Name (`name`)	`payee.user_name`	Required; ≤35 characters; Alphanumeric boundaries
Name (`givenName` / `surname`)	`payee.first_name` / `payee.last_name`	Alphanumeric boundaries
`details`	Format: `${PaymentMethod} -${Name}`	Alphanumeric boundaries
Bank Name (`BANK_NAME`)	`payee.bank_name`	≤35 characters
Bank Address (`BANK_ADDRESS`)	`payee.country`	≤35 characters; Must comply with SWIFT character set
`endToEndId`	System-generated value (15 chars)	ACH ≤17, SWIFT ≤36; Alphanumeric boundaries
`referenceNumber`	Payout remarks	Alphanumeric boundaries
`purposeCode`	Mapped purpose code	Alphanumeric boundaries
Account Number (`accountNumber`)	`payee.account_number`	ACH channel limit ≤17 chars; Alphanumeric boundaries
Account Country Code	`payee.country`	2-character ISO code; Alphanumeric boundaries
Financial Institution ID (`financialInstitutionId`)	ACH: `bank_code`; SWIFT: `bic_swift`	ACH strictly requires a 9-digit routing number; Alphanumeric boundaries
Address (`street1`)	`payee.payee_address.line1`	≤70 characters; Must comply with SWIFT character set
Address (`street2`)	`payee.payee_address.line2`	≤35 characters; Must comply with SWIFT character set
Address (`city`)	`payee.payee_address.city`	≤35 characters; Must comply with SWIFT character set
Address (`state`)	`payee.payee_address.state`	≤35 characters; Alphanumeric boundaries
Address (`zip`)	`payee.payee_address.postCode`	≤16 characters; Alphanumeric boundaries
Address (`country`)	`payee.country`	≤2 characters
Payment Purpose Memo (`PAYMENT_PURPOSE_MEMO`)	Purpose code dictionary mapping, falls back to `Payment Purpose: xxx`	Alphanumeric boundaries
Intermediary Bank BIC	`payee.intermediary_bank_swift_code`	Validated only for SWIFT when provided; Alphanumeric boundaries
OUR_PARTY Account/Routing/Country	Fixed values: `0` / `021508219` / `PR`	Alphanumeric boundaries

Error Code Summary 📊

Intercept Scenario	HTTP Business Code (`code`)	Prompt Message (`message`) Format
`PayeeValidator` strict check failure	`100001`	English error prompts; multiple errors will be concatenated with `;`
DTO pipeline validation failure	`999901`	Standard i18n localized validation prompts
`va_005` channel pre-validation failure	`100001`	Original English message returned by the channel validator
Invalid purpose code	`100001`	General business error prompt

Integration Regression Testing Recommendations 🧪

To ensure a smooth transition of your integration, please verify compatibility based on the following scenarios.

Business Process	Test Case & Expected Result
Create Payee	1. Submit a normal US ACH payee (with full address): Should succeed. 2. Submit a GB alphanumeric postal code and a company name containing Chinese characters: Should succeed (Regex supports Unicode). 3. `accountNumber` reaches 40 characters or contains `/`: Should return 400. 4. `payeeAddress` missing `postCode` or `city`: Should return 400.
Update Payee	1. Full update echoing all fields (including `bankAddress`): Should succeed. 2. Omit `bankAddress`: Should succeed, but the system will clear the existing bank address stored in the DB.
Submit Payout	1. va_005 + ACH, routing number is exactly 9 digits: Should succeed. 2. va_005 + ACH, routing number is not 9 digits: Should directly return 400 upon order creation. 3. va_005 + WIRE, routing number is not 9 digits: Should succeed (Not restricted by ACH rules). 4. Other channels (e.g., va_006 / va_007): Behavior remains unchanged; unaffected by pre-validation. 5. Retry with the same `callId`: Idempotent behavior remains unchanged.