Antom, leading provider of tailored payment solutions
Contact Us
登 录

bindBeneficiary

POST /v1/aba/accounts/bindBeneficiary

调用此接口绑定收款人信息。您可关联其银行卡、支付账户或 Antom 全球商家账户至您的账户。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息，有关报文头的结构信息，请参阅：

注意：将每个字段（除数组外）的数据类型设置为字符串。这意味字段值必须使用双引号（" "）括起来。例如：

  • 如果字段的数据类型为整数属性，且其值为 20，设置为 "20"。
  • 如果字段的数据类型为布尔属性，且其值为 true，设置为 "true"。

入参

bindBeneficiaryRequestId String  REQUIRED

用于标识受益人绑定请求的专属 ID。

更多信息：

  • 此为幂等字段。
  • 最大长度：64 字符

beneficiaryType String  REQUIRED

收款人账户类型，该字段用于确定支付或转账逻辑以及资金流动路径，其值必须符合目标接口的允许选项。

对于 createPayout 接口，支持的值包括：

  • THIRD_PARTY_PERSONAL_BANK_ACCOUNT：表示收款人账户类型为第三方个人银行账户。
  • THIRD_PARTY_COMPANY_BANK_ACCOUNT：表示收款人账户类型为第三方对公银行账户。
  • PERSONAL_BANK_ACCOUNT：表示收款人账户类型为同名个人银行账户。
  • COMPANY_BANK_ACCOUNT：表示收款人账户类型为同名对公银行账户。

对于 createPayout 接口（中国区），支持的值包括：

  • RELATED_MERCHANT_COMPANY_BANK_ACCOUNT：表示收款人账户类型为关联企业对公银行账户。
  • RELATED_MERCHANT_ALIPAY_COMPANY_ACCOUNT：表示收款人账户类型为关联企业支付宝对公账户。

对于 createPayout 接口，支持的值包括：

  • ANTOM_BIZ_ACCOUNT：表示收款人账户类型为 Antom 全球商家账户。

beneficiaryAlipayAccount Object  

收款人支付宝账户详情。

注意：bindBeneficiary 接口和 inquireBeneficiary 接口的字段名称与 inquireBeneficiaryTemplate 接口中的 alipayTemplateData 字段名称一致，确保数据映射统一。

beneficiaryBankAccount Object  

收款人银行卡账户详情。

注意：bindBeneficiary 接口和 inquireBeneficiary 接口的字段名称与 inquireBeneficiaryTemplate 接口中的 cardTemplateData 字段名称一致，确保数据映射统一。

beneficiaryAntomBizAccount Object  

收款人 Antom 全球商家账户详情。

注意：bindBeneficiary 接口和 inquireBeneficiary 接口的字段名称与 inquireBeneficiaryTemplate 接口中的 antomBizAccountTemplateData 字段名称一致，确保数据映射统一。

countryCode String  

银行所在国家或地区的 2 字母代码，遵循 ISO 3166 国家代码标准。

更多信息：

  • 最大长度：2 字符

currency String  

符合 ISO 4217 标准的 3 字母货币代码。

注意：若 beneficiaryType 不包含 ​ALIPAY_COMPANY_ACCOUNT​，则此字段必填。

更多信息：

  • 最大长度：3 字符

referenceBeneficiaryId String  

商户用于标识受益人的专属 ID。

更多信息：

  • 最大长度：64 字符

beneficiaryNick String  REQUIRED

商户为方便识别收款人而设置的收款人昵称。

更多信息：

  • 最大长度：70 字符

cnSettlementMode String  

人民币提现的结算模式。有效值包括：

  • CNY_ONSHORE: 境内人民币账户。
  • CNH_OFFSHORE: 境外离岸人民币账户 (CNH)。

出参

result Result  REQUIRED

表明此接口是否调用成功。

Show child parameters

beneficiary Beneficiary  

收款人详情。

Show child parameters
API Explorer

请求

URL

Method
POST
请求体

响应

响应体

结果码

结果码值结果码信息行动建议
SUCCESSS成功

接口调用成功，无需进一步操作。

PROCESS_FAILF发生了一般业务失败。

请勿重试。通常需要人工干预。建议联系 Antom 技术支持团队解决问题。

PARAM_ILLEGALF存在非法参数。例如，非数字输入或无效日期。

检查并验证请求字段（包括头部字段和主体字段）是否正确且有效。有关每个接口的字段详细信息，请参阅具体的接口结构部分。

UNKNOWN_EXCEPTIONU由于未知原因导致API失败。

服务可能已宕机，请稍后重试。如果问题持续存在，请联系 Antom 技术支持团队。

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过限制。

再次调用接口以解决问题。如果问题持续存在，请联系 Antom 技术支持团队。

OAUTH_FAILFOAuth 过程失败。

请联系 Antom 技术支持团队获取详细原因。

INVALID_APIF调用的接口无效或未激活。

检查是否调用了正确的接口。

INVALID_CLIENTF客户端无效。

客户端 ID 不存在或无效。

INVALID_SIGNATUREF签名无效。

确保请求使用有效的签名进行正确签名。

CURRENCY_NOT_SUPPORTF货币不被支持。

确保货币输入正确并重试。

METHOD_NOT_SUPPORTEDF服务器未实现请求的 HTTP 方法。

确保使用 POST 方法。

UN_SUPPORT_BUSINESSF不支持的业务。

使用了无效参数（例如货币不正确）。请使用正确的信息重试。

USER_NOT_EXISTF用户不存在。

请使用正确的用户信息重试。

RISK_REJECTF由于风险控制原因，转账被拒绝。

提示用户请求因风险控制失败而被拒绝。

REPEAT_BIND_BENEFICIARY_REQUESTU重复绑定收款人请求。

检查收款人是否已通过 inquireBeneficiary 接口成功绑定。

EXCEED_MAX_COUNT_LIMITF超出最大计数限制。

确保数据在限制范围内并重试。

USER_NO_PERMISSIONF用户没有权限。

检查用户权限并重试。

BENEFICIARY_ALREADY_EXISTEDU收款人已存在。

检查收款人是否已通过 inquireBeneficiary 接口成功绑定。

REPEAT_REQ_INCONSISTENTF重复请求不一致。

确保所有请求字段相同。

REFERENCE_BENEFICIARY_ID_EXISTF参考收款人 ID 已存在。

检查收款人是否已成功绑定。

SAME_NAME_CHECK_FAILF同名称参数验证失败。

检查收款人名称是否与商户相同。

CARD_TEMPLATE_NOT_EXISTF未找到符合条件的卡模板。

检查是否使用了正确的收款人模板。