Create a Beneficiary

Register a new payment beneficiary — a bank account or digital wallet (Alipay accounts only for now) to which you can send payouts. Upon creation, a unique beneficiary ID is generated, which can be referenced when initiating a payment.
Request Parameters
When a Beneficiary holds NON_CNY_BANK_ACCOUNT
accountTypestring
required
Type of beneficiary account.

Valid Values:

BANK_ACCOUNT — Bank account.
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 — The beneficiary is your own account (same account holder name).
THIRD_PARTY — A third party.
RELATED_MERCHANT — An affiliated business entity.
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 of the beneficiary's bank or wallet (e.g., US, GB).
currencystring
required
Three-letter ISO 4217 currency code for the beneficiary account (e.g., USD, EUR).
bankDetailsBankDetail
Bank account details. Required when accountType is BANK_ACCOUNT.
Show child parametersShow child parameters
nicknamestring
Display name for this beneficiary (e.g., Supplier A). Not displayed on bank statements. Max 70 characters.
paymentTypestring
Preferred payment rail. If omitted, both LOCAL and CROSS are supported.

Valid Values:

LOCAL — Local clearing network (e.g., ACH, SEPA).
CROSS — Cross-border transfer. Supports international payments.
referenceBeneficiaryIdstring
Your internal reference ID for this beneficiary. Max 64 characters.
phonestring
Beneficiary contact phone number. Max 64 characters.
emailstring
Beneficiary contact email address. Max 64 characters.
citystring
Beneficiary's city. Max 64 characters.
addressstring
Beneficiary's street address. Max 256 characters.
Response Parameters
resultResult
See Result.
idstring
Unique identifier for this beneficiary. Use this ID in payout requests.
referenceBeneficiaryIdstring
Your internal reference ID for this beneficiary.
statusstring
Current lifecycle status. See BeneficiaryStatus. The beneficiary must reach ACTIVE before it can receive payments.
regionstring
ISO 3166 two-letter country/region code.
accountTypestring
Type of beneficiary account.
entityTypestring
Beneficiary entity type.
relationTypestring
Relationship type.
classificationCodestring
Relationship classification code.
currencystring
Account currency. Three-letter ISO 4217 code.
bankDetailsBankDetail
Bank account details. Returned when accountType is BANK_ACCOUNT. Contains the same fields as the request bankDetails.
Show child parametersShow child parameters
walletDetailsWalletDetail
Wallet account details. Returned when accountType is DIGITAL_WALLET. Contains the same fields as the request walletDetails.
Show child parametersShow child parameters
paymentTypestring
Supported payment rail.
nicknamestring
Display name for this beneficiary.
phonestring
Beneficiary contact phone number.
emailstring
Beneficiary contact email address.
citystring
Beneficiary's city. Max 64 characters.
addressstring
Beneficiary's street address. Max 256 characters.
createdAtdatetime
Timestamp when this beneficiary was created. ISO 8601 extended format.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
RISK_REJECTFThe request is rejected for risk control reasons.Inform the end user that the request failed compliance review.
UN_SUPPORT_BUSINESSFUnsupported business.Verify all parameter values are within supported ranges and retry.
BENEFICIARY_ALREADY_EXISTEDFBeneficiary already exists.Call Query a Beneficiary to check if the beneficiary is already registered.
EXCEED_MAX_COUNT_LIMITFThe maximum count limit has been exceeded.Reduce the number of items or contact WorldFirst support to increase the limit.
REFERENCE_BENEFICIARY_ID_EXISTFThe reference beneficiary ID already exists.Use a unique reference beneficiary ID.
ALIPAY_ACCOUNT_NOT_EXISTFThe Alipay account does not exist.Verify the Alipay account information and retry.
ALIPAY_ACCOUNT_INFO_ERRORFThe Alipay account information is incorrect.Verify the Alipay account details and retry with correct information.
CARD_TEMPLATE_NOT_EXISTFNo card templates matched the query conditions.Verify the required information for the card template and retry.
Definition
POST /api/open/v1/beneficiaries/create
Request
{
"region": "US",
"currency": "USD",
"nickname": "Supplier A",
"accountType": "BANK_ACCOUNT",
"entityType": "PERSONAL",
"relationType": "THIRD_PARTY",
"classificationCode": "0001",
"bankDetails": {
  "accountNumber": "50001**121",
  "accountHolderName": {
    "fullName": "TestName"
  },
  "routingNumber": "0210000****21",
  "bankName": "JPMorgan Chase Bank, NA",
  "beneficiaryRegion": "US",
  "beneficiaryState": "CA",
  "beneficiaryPostalCode": "90028"
},
"city": "Los Angeles",
"address": "6767 Hollywood Test Address"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success.",
  "resultStatus": "S"
},
"id": "202604011001010101",
"status": "ACTIVE",
"createdAt": "2026-03-30T12:08:56+08:00",
"currency": "USD",
"region": "US",
"nickname": "Supplier A",
"accountType": "BANK_ACCOUNT",
"entityType": "PERSONAL",
"relationType": "THIRD_PARTY",
"classificationCode": "0001",
"bankDetails": {
  "accountNumber": "50001**121",
  "accountHolderName": {
    "fullName": "TestName"
  },
  "routingNumber": "0210000****21",
  "bankName": "JPMorgan Chase Bank, NA",
  "beneficiaryRegion": "US",
  "beneficiaryState": "CA",
  "beneficiaryPostalCode": "90028"
},
"city": "Los Angeles",
"address": "6767 Hollywood Test Address"
}