Query a Beneficiary

Retrieve the full details of an existing beneficiary by its unique ID. Use this endpoint to check a beneficiary's status and related properties.
Request Parameters
idstring
required
Unique identifier of the beneficiary to retrieve.
Response Parameters
resultResult
See Result.
idstring
Unique identifier for this beneficiary. Use this ID for subsequent update, delete, and payout operations.
referenceBeneficiaryIdstring
Your internal reference ID for this beneficiary.
statusstring
Current lifecycle status. See BeneficiaryStatus. Only ACTIVE beneficiaries can receive payments.
regionstring
ISO 3166 two-letter country/region code.
currencystring
Account currency. Three-letter ISO 4217 code.
accountTypestring
Type of beneficiary account (BANK_ACCOUNT or DIGITAL_WALLET).
entityTypestring
Beneficiary entity type (COMPANY or PERSONAL).
relationTypestring
Relationship type (SAME_NAME, THIRD_PARTY, or RELATED_MERCHANT).
classificationCodestring
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.
bankDetailsBankDetail
Bank account details. Returned when accountType is BANK_ACCOUNT. See Create a Beneficiary for the full field list.
Show child parametersShow child parameters
walletDetailsWalletDetail
Wallet account details. Required when accountType is DIGITAL_WALLET and support ALIPAY wallet only for adding a beneficiary.
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.
addressstring
Beneficiary's street address.
citystring
Beneficiary's city.
createdAtdatetime
Timestamp when this beneficiary was created. ISO 8601 extended format.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
UN_SUPPORT_BUSINESSFUnsupported business.Verify all parameter values are within supported ranges and retry.
BENEFICIARY_NOT_EXISTFThe beneficiary does not exist.Verify the beneficiary ID is correct. Use List Beneficiaries to find the right ID.
Definition
POST /api/open/v1/beneficiaries/query
Request
{
"id": "20260412123235345"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success.",
  "resultStatus": "S"
},
"id": "20260412123235345",
"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"
}