Validate a Beneficiary

Pre-validate beneficiary information before calling Create a Beneficiary or initiating a payout. This endpoint checks whether the provided beneficiary fields meet all format and constraint requirements without creating a beneficiary. Use it to surface field-level errors early in your integration flow.
Request Parameters
accountTypestring
required
Type of beneficiary account.

Valid Values:

BANK_ACCOUNT — Bank account.
DIGITAL_WALLET — Digital wallet.
entityTypestring
required
Beneficiary entity type.

Valid Values:

COMPANY — Corporate entity.
PERSONAL — Individual.
relationTypestring
required
Relationship between your account and the beneficiary.

Valid Values:

SAME_NAME — Same-name transfer.
THIRD_PARTY — Third-party transfer.
RELATED_MERCHANT — Related merchant transfer.
classificationCodestring conditional
Relationship classification code when relationType = THIRD_PARTY.

Valid Values:

0001 — Goods Trade
0002 — Advertising/Marketing
0003 — Logistics/Freight Forwarding/Warehousing.
0004 — Financial & Tax Services
0005 — Technology Services.
regionstring
required
ISO 3166 two-letter country/region code (e.g., US, GB).
currencystring
required
Three-letter ISO 4217 currency code.
paymentTypestring
Payment rail to validate against.

Valid Values:

LOCAL — Local clearing network.
CROSS — Cross-border transfer.
nicknamestring
Display name. Max 70 characters.
phonestring
Contact phone number.
emailstring
Contact email address.
citystring
Beneficiary's city. Max 64 characters.
addressstring
Beneficiary's street address. Max 256 characters.
referenceBeneficiaryIdstring
Your internal reference ID for this beneficiary. Max 64 characters.
serviceCategorystring
Business category of the supplier or recipient. Follow the beneficiary template requirements for this field.
bankDetailsBankDetail
Bank account details to validate. Required when accountType is BANK_ACCOUNT.
Show child parametersShow child parameters
walletDetailsWalletDetail
Wallet account details to validate. Required when accountType is DIGITAL_WALLET.
Show child parametersShow child parameters
Response Parameters
resultResult
See Result. A SUCCESS result with an empty array means the input is valid.
validationErrorsarray
Field-level validation errors. Empty when all fields pass. Maximum 50 errors.
Show child parametersShow child parameters
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
UN_SUPPORT_BUSINESSFUnsupported business.Verify all parameter values are within supported ranges and retry.
CONTRACT_NOT_EXISTFThe required contract does not exist.Ensure the required service contract is in place before initiating this operation. Contact WorldFirst support.
CARD_TEMPLATE_NOT_EXISTFNo card templates matched the query conditions.Verify the required information for the card template and retry.
VALIDATE_FAILFValidation failed.Verify the error message, correct and retry
Definition
POST /api/open/v1/beneficiaries/validate
Request
{
"region": "US",
"currency": "USD",
"accountType": "BANK_ACCOUNT",
"entityType": "PERSONAL",
"relationType": "THIRD_PARTY",
"bankDetails": {
  "beneficiaryRegion": "US",
  "accountNumber": "50001121",
  "routingNumber": "021000021"
}
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"validationErrors": []
}