bindBeneficiary
Use this interface to to bind the beneficiary by connecting their bank card, Alipay account, or Antom business account information to your account.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：
Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
- If the data type of a field is Integer and its value is 20, set it as "20".
- If the data type of a field is Boolean and its value is
true, set it as "true".
Request parameters
bindBeneficiaryRequestId String REQUIRED
Unique ID assigned by the user to identify a request for beneficiary binding.
More information:
- This field is an API idempotency field.
- Maximum length: 64 characters
beneficiaryType String REQUIRED
The type of the beneficiary's card. This field serves as a token to determine the payment or transfer logic and fund flow path. The value must match the allowed options for the target API.
For createPayout API, supported values include:
THIRD_PARTY_PERSONAL_BANK_ACCOUNT: Indicates the type of the beneficiary's card is the personal bank account of the third-party beneficiary.THIRD_PARTY_COMPANY_BANK_ACCOUNT: Indicates the type of the beneficiary's card is the company bank account of the third-party beneficiary.PERSONAL_BANK_ACCOUNT: Indicates the type of the beneficiary's card is the personal bank account of the same-name beneficiary.COMPANY_BANK_ACCOUNT: Indicates the type of the beneficiary's card is the company bank account of the same-name beneficiary.
For createPayout API (China-specific), supported values include:
RELATED_MERCHANT_COMPANY_BANK_ACCOUNT: Indicates the type of the beneficiary's card is the company bank account of the related company.RELATED_MERCHANT_ALIPAY_COMPANY_ACCOUNT: Indicates the type of the beneficiary's card is the company alipay account of the related company.
For createTransfer API, supported value include:
ANTOM_BIZ_ACCOUNT: Indicates the type of the beneficiary's card is Antom Business Account.
beneficiaryAlipayAccount Object
Details about the beneficiary's Alipay account.
Note: The field names in the bindBeneficiary and inquireBeneficiary response match the field names of alipayTemplateData in inquireBeneficiaryTemplate API, ensuring consistent data mapping.
beneficiaryBankAccount Object
Details about the beneficiary's bank account.
Note: The field names in the bindBeneficiary and inquireBeneficiary response match the field names of cardTemplateData in inquireBeneficiaryTemplate API, ensuring consistent data mapping.
beneficiaryAntomBizAccount Object
Details about the beneficiary's wallet account.
Note: The field names in the bindBeneficiary and inquireBeneficiary response match the field names of antomBizAccountTemplateData in inquireBeneficiaryTemplate API, ensuring consistent data mapping.
countryCode String
The 2-letter country or region code where the bank is located, following the ISO 3166 Country Codes standard.
More information:
- Maximum length: 2 characters
currency String
The 3-letter currency code that follows the ISO 4217 standard.
Note: This field is required if beneficiaryType does not contain ALIPAY_COMPANY_ACCOUNT.
More information:
- Maximum length: 3 characters
referenceBeneficiaryId String
The unique ID defined by the merchant to identify a beneficiary.
More information:
- Maximum length: 64 characters
beneficiaryNick String REQUIRED
The nickname of the beneficiary.
More information:
- Maximum length: 70 characters
cnSettlementMode String
Currency for withdrawal to CNY. Valid values include:
CNY_ONSHORE: beneficiary in mainland China.CNH_OFFSHORE: beneficiary overseas (CNH).
Response parameters
result Result REQUIRED
Indicates whether this API call is successful.
beneficiary Beneficiary REQUIRED
Details about the beneficiaries.
Note: This field is returned on demand only when the value of result.resultStatus is S.
Request
Response
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | success. | The API is called successfully, and no further action is needed. |
| PROCESS_FAIL | F | A general business failure occurred. Do not retry. | Human intervention is usually needed. It is recommended that you contact our Technical Support Team to resolve the issue. |
| PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. | Check and verify whether the request fields, including the header fields and body fields, are correct and valid. |
| UNKNOWN_EXCEPTION | U | API failed due to unknown reason. | The service might be down, retry later. If the issue persists, contact our Technical Support Team. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Call the interface again to resolve the issue. If the issue persists, contact our Technical Support Team. |
| OAUTH_FAIL | F | OAuth process failed. | Contact our Technical Support Team for detailed reasons. |
| INVALID_API | F | The called API is invalid or not active. | Check whether the correct API is being called. |
| INVALID_CLIENT | F | The client is invalid. | The Client ID does not exist or is invalid. |
| INVALID_SIGNATURE | F | The signature is invalid. | Make sure the request is properly signed with a valid signature. |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. | Make sure the currency input is correct and try again. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. | Ensure the HTTP method is POST. |
| UN_SUPPORT_BUSINESS | F | Unsupported business. | Invalid parameters are used e.g. currency is incorrect. Retry with the correct information. |
| USER_NOT_EXIST | F | The user does not exist. | Retry with the correct user information. |
| RISK_REJECT | F | The transfer is rejected for risk control reasons. | Prompt the user that the request is rejected because the risk control failed. |
| REPEAT_BIND_BENEFICIARY_REQUEST | U | Repeated request to bind a beneficiary. | Check whether the beneficiary has already been successfully bound with the inquiryBeneficiary API. |
| EXCEED_MAX_COUNT_LIMIT | F | Exceed max count limit. | Ensure the data lies within the limit and try again. |
| USER_NO_PERMISSION | F | User does not have permission. | Check the permission of the user and retry. |
| BENEFICIARY_ALREADY_EXISTED | U | Beneficiary already existed. | Check whether the beneficiary has already been successfully bonded with the inquiryBeneficiary API. |
| REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | Ensure all the fields in the requests are the same. |
| REFERENCE_BENEFICIARY_ID_EXIST | F | Reference beneficiary id exist. | Check whether the beneficiary has already been successfully bound. |
| SAME_NAME_CHECK_FAIL | F | Verification of parameters with the same name failed. | Check whether the beneficiary name is the same with merchant. |
| CARD_TEMPLATE_NOT_EXIST | F | No card templates met the query conditions. | Check whether the correct beneficiary template has been used. |