WorldFirst DocsWorldFirst DocsDOCS

bindBeneficiary

POST: /amsin/api/v1/business/account/bindBeneficiary

需要签名验签

绑定收款人时，集成商可调用此接口将收款人的银行卡信息添加至万里汇账号中。

报文结构

万里汇接口报文结构包括：请求头、请求体。关于头信息，详见：

请求参数

字段名

数据类型

是否必填

描述

bindBeneficiaryRequestId

字符串

是

由集成商定义、用于唯一标识某次收款人绑定请求。

更多信息：

  • 本字段为幂等字段，具体详见幂等字段介绍
  • 字段最大长度：64

customerId

字符串

是（有条件必填）

由万里汇定义、用于唯一标识某万里汇账户。

更多信息：

  • customerId和accessToken 不能同时为空
  • 字段最大长度：64

accessToken

字符串

是（有条件必填）

用于OAuth校验的访问令牌

更多信息：

  • customerId和accessToken 不能同时为空
  • 字段最大长度：64

beneficiaryBankAccount

BeneficiaryBankAccount 对象

否

收款人银行账户信息，例如账户持有人、国家/地区、收款人银行BIC码等。

beneficiaryType

字符串

是

收款人账户类型

取值范围为：

  • THIRD_PARTY_COMPANY_BANK_ACCOUNT
  • THIRD_PARTY_PERSONAL_BANK_ACCOUNT

类型信息详见：BeneficiaryType

countryCode

字符串

是

收款人所在国家/地区，为 ISO 3166标准规定的二位字母国家地区码。

  • 字段最大长度：2

currency

字符串

是

币种信息，为 ISO 4217 标准规定的三位字母货币代码。 现阶段字段取值范围为：

  • USD,EUR,GBP,NZD,CAD,AUD,JPY,SGD,HKD,CNH

beneficiaryNick

字符串

是

由用户定义的收款人昵称，可以帮助用户更方便地识别该收款人。

templateCategory

字符串

否

绑定收款人使用的模板类型，可取值为：

  • GENERAL_TEMPLATE: 常规模板，对应inquiryBeneficiaryTemplate 接口返回的 cardTemplateData 
  • LOCAL_TEMPLATE: 本地模板，对应inquiryBeneficiaryTemplate 接口返回的 localCardTemplateData 
  • CROSS_BORDER_TEMPLATE：跨境模板，对应inquiryBeneficiaryTemplate 接口返回的 crossBorderCardTemplateData 

更多信息：

  • 默认取值为GENERAL_TEMPLATE

referenceBeneficiaryId

字符串

否

由集成商定义的收款人唯一标识ID

更多信息：

  • 字段最大长度：64

响应参数

字段名

数据类型

是否必填

描述

result

Result 对象

是

代表接口调用结果

beneficiary

Beneficiary 对象

是

收款人信息

响应处理

集成商调用接口后，万里汇返回集成商API调用结果：result.resultStatus和beneficiary.status。

  • result.resultStatus代表API调用结果
  • beneficiary.status代表提交的收款人状态

result.resultStatus取值范围为：

Result status

描述

S

接口调用成功

F

接口调用失败，具体原因参见result.resultCode

U

调用结果未知，需重试API请求。

重试策略：

  • 重试次数上限：7次
  • 重试时间间隔：5分钟、10分钟、20分钟、40分钟、80分钟、160分钟、320分钟

若上述重试均未成功，联系万里汇技术支持。

结果码

result.resultCode

系统结果码

resultCode

resultStatus

resultMessage

处理建议

SUCCESS

S

Success

PROCESS_FAIL

F

A general business failure occurred. Do not retry.

需要人工介入，联系万里汇技术支持以解决此问题

PARAM_ILLEGAL

F

Illegal parameters exist. For example, a non-numeric input, or an invalid date.

参考API文档页面，确认请求头和传参是否正确

UNKNOWN_EXCEPTION

U

API failed due to unknown reason.

服务器错误，若稍后重试问题依旧，联系万里汇技术支持以解决问题

REQUEST_TRAFFIC_EXCEED_LIMIT

U

The request traffic exceeds the limit.

重试，若问题依旧，联系万里汇技术支持

OAUTH_FAIL

F

OAuth process failed.

联系万里汇技术支持了解详情

INVALID_API

F

The called API is invalid or not active.

确认是否调用正确的API

INVALID_CLIENT

F

The client is invalid.

Client ID不存在或无效，需确认信息正确

INVALID_SIGNATURE

F

The signature is invalid.

确认请求正确加签，具体参见：

METHOD_NOT_SUPPORTED

F

The server does not implement the requested HTTP method.

确认HTTP请求方法为POST

业务结果码

resultCode

resultStatus

resultMessage

处理建议

UN_SUPPORT_BUSINESS

F

Unsupported business.

包含无效参数（如货币代码错误），使用正确的参数重试

USER_NOT_EXIST 

F

The user does not exist.

使用正确的用户信息重试

RISK_REJECT

F

The transfer is rejected for risk control reasons.

集成商需提示用户，该请求因风控审核未通过被拒绝

REPEAT_BIND_BENEFICIARY_REQUEST

U

Repeated request to bind a beneficiary.

调用 inquiryBeneficiary 接口以检查收款人是否已成功绑定

EXCEED_MAX_COUNT_LIMIT

F

Exceed max count limit.

使用正确的参数重试

USER_NO_PERMISSION

F

User does not have permission.

检查用户权限是否正确并重试

BENEFICIARY_ALREADY_EXISTED

F

Beneficiary already existed.

调用 inquiryBeneficiary 接口以检查收款人是否已成功绑定

REPEAT_REQ_INCONSISTENT

F

Repeated requests are inconsistent.

确认请求中所有参数一致

REFERENCE_BENEFICIARY_ID_EXIST

F

Reference beneficiary id exist.

确认收款人是否已成功绑定

CARD_TEMPLATE_NOT_EXIST

F

No card templates met the query conditions.

确认使用的模板类型是否正确

示例代码

使用常规模板

请求体范例

copy
{
    "bindBeneficiaryRequestId": "*****",
    "customerId": "*****",
    "beneficiaryType": "THIRD_PARTY_COMPANY_BANK_ACCOUNT",
    "countryCode": "DE",
    "currency": "EUR",
    "beneficiaryNick": "nickname",
    "templateCategory": "GENERAL_TEMPLATE",
    "referenceBeneficiaryId": "unique beneficiary id",
    "beneficiaryBankAccount": {
        "bankAccountLocalName": "*****",
        "bankBIC": "CHASDE*****",
        "bankAccountIBAN": "DE111234432112345*****"
    }
}

请求代码范例

copy
var jsonStr="{\"customerId\":\"*****\",\"bindBeneficiaryRequestId\":\"*****\",\"beneficiaryType\":\"THIRD_PARTY_COMPANY_BANK_ACCOUNT\",\"countryCode\":\"DE\",\"currency\":\"EUR\",\"beneficiaryNick\":\"ABC\",\"beneficiaryBankAccount\":{\"bankAccountName\":\"ABC\",\"bankName\":\"CHAS BANK\",\"bankBIC\":\"*****\",\"bankAccountIBAN\":\"*****\"}}";
var client = new RestClient("http://{domain_name}.com/amsin/api/v1/business/account/bindBeneficiary");
var request = new RestRequest(Method.POST);
request.AddHeader("client-id","*****");
request.AddHeader("request-time","2022-05-17T11:19:20+08:00");
request.AddHeader("Content-Type","application/json");
request.AddHeader("signature","algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****");
request.AddParameter("application/json; charset=utf-8", jsonStr, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
copy
url = "http://{domain_name}.com/amsin/api/v1/business/account/bindBeneficiary"
headers = {
    "client-id": "*****",
    "request-time": "2022-05-17T11:19:20+08:00",
    "Content-Type": "application/json",
    "signature": "algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****"
}
datas ={"customerId":"*****","bindBeneficiaryRequestId":"*****","beneficiaryType":"THIRD_PARTY_COMPANY_BANK_ACCOUNT","countryCode":"DE","currency":"EUR","beneficiaryNick":"ABC","beneficiaryBankAccount":{"bankAccountName":"ABC","bankName":"***BANK","bankBIC":"CHASD*****","bankAccountIBAN":"DE******"}}

res = requests.post(url=url, data=json.dumps(datas), headers=headers)
copy
CloseableHttpClient client = HttpClientBuilder.create().build();
HttpPost httpPost = new HttpPost("http://{domain_name}.com/amsin/api/v1/business/account/bindBeneficiary");
httpPost.addHeader("client-id", "*****");
httpPost.addHeader("request-time", "2022-05-17T11:19:20+08:00");
httpPost.addHeader("signature","algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****" );
httpPost.addHeader("Content-Type","application/json");
StringEntity entity = new StringEntity("{\"customerId\":\"*****\",\"bindBeneficiaryRequestId\":\"*****\",\"beneficiaryType\":\"THIRD_PARTY_COMPANY_BANK_ACCOUNT\",\"countryCode\":\"DE\",\"currency\":\"EUR\",\"beneficiaryNick\":\"ABC\",\"beneficiaryBankAccount\":{\"bankAccountName\":\"ABC\",\"bankName\":\"CHAS BANK\",\"bankBIC\":\"CHASD*****\",\"bankAccountIBAN\":\"DE******\"}}");
httpPost.setEntity(entity);
CloseableHttpResponse response = client.execute(httpPost);
copy
var xhr = new XMLHttpRequest;
xhr.open("POST","http://{domain_name}.com/amsin/api/v1/business/account/bindBeneficiary",true)
xhr.setRequestHeader("client-id","*****");
xhr.setRequestHeader("request-time","2022-05-17T11:19:20+08:00");
xhr.setRequestHeader("Content-Type","application/json");
xhr.setRequestHeader("signature","algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****");
xhr.send("{\"customerId\":\"*****\",\"bindBeneficiaryRequestId\":\"*****\",\"beneficiaryType\":\"THIRD_PARTY_COMPANY_BANK_ACCOUNT\",\"countryCode\":\"DE\",\"currency\":\"EUR\",\"beneficiaryNick\":\"ABC\",\"beneficiaryBankAccount\":{\"bankAccountName\":\"ABC\",\"bankName\":\"CHAS BANK\",\"bankBIC\":\"CHASD*****\",\"bankAccountIBAN\":\"DE******\"}}");

响应体范例

copy
{
    "beneficiary": {
        "beneficiaryBankAccount": {
            "bankAccountIBAN": "DE111234432112345*****",
            "bankAccountLocalName": "*****",
            "bankBIC": "CHASDE*****"
        },
        "beneficiaryNick": "nickname",
        "beneficiaryToken": "ALIPAYjIIt8sp8SiKROf4tqBxXk4g+21Tgtijnngj40UiQ6cRK+o8wVoyLd082wvr5Jd7+ecG+d5jFylCRsGrtK8j*****",
        "beneficiaryType": "THIRD_PARTY_COMPANY_BANK_ACCOUNT",
        "bindBeneficiaryRequestId": "*****",
        "countryCode": "DE",
        "currency": "EUR",
        "referenceBeneficiaryId": "unique beneficiary id",
        "status": "SUCCESS"
    },
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    }
}

使用本地模板

请求体范例

copy
{
    "customerId":"*****",
    "bindBeneficiaryRequestId": "*****",
    "beneficiaryType": "THIRD_PARTY_COMPANY_BANK_ACCOUNT",
    "countryCode":"DE",
    "currency":"EUR",
    "beneficiaryNick":"NickABC",
    "templateCategory":"LOCAL_TEMPLATE",
    "beneficiaryBankAccount": {
        "bankAccountName":"shen***",
        "bankBIC":"CHASDE*****",
        "bankAccountIBAN":"DE315001051765761*****"
    }
}

响应体范例

copy
{
    "beneficiary": {
        "beneficiaryBankAccount": {
            "bankAccountIBAN": "DE315001051765761*****",
            "bankAccountName": "shen***",
            "bankBIC": "CHASDE*****"
        },
        "beneficiaryNick": "shen***",
        "beneficiaryToken": "ALIPAYjIIt8*****",
        "beneficiaryType": "THIRD_PARTY_COMPANY_BANK_ACCOUNT",
        "bindBeneficiaryRequestId": "*****",
        "countryCode": "DE",
        "currency": "EUR",
        "status": "SUCCESS"
    },
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    }
}

使用跨境模板

请求体范例

copy
{
    "customerId":"*****",
    "bindBeneficiaryRequestId": "*****",
    "beneficiaryType": "THIRD_PARTY_COMPANY_BANK_ACCOUNT",
    "countryCode":"DE",
    "currency":"EUR",
    "beneficiaryNick":"NickABC",
    "templateCategory":"CROSS_BORDER_TEMPLATE",
    "beneficiaryBankAccount": {
        "bankAccountName":"shen***",
        "bankAccountLocalName":"shen***",
        "bankBIC":"CHASDE*****",
        "bankAccountIBAN":"DE315001051765761*****"
    }
}

响应体范例

copy
{
    "beneficiary": {
        "beneficiaryBankAccount": {
            "bankAccountIBAN": "DE315001051765761*****",
            "bankAccountLocalName": "shen***",
            "bankAccountName": "shen***",
            "bankBIC": "CHASDE*****"
        },
        "beneficiaryNick": "NickABC",
        "beneficiaryToken": "ALIPAYjIIt8*****",
        "beneficiaryType": "THIRD_PARTY_COMPANY_BANK_ACCOUNT",
        "bindBeneficiaryRequestId": "*****",
        "countryCode": "DE",
        "currency": "EUR",
        "status": "SUCCESS"
    },
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    }
}

使用 referenceBeneficiaryId

请求体范例

copy
{
    "customerId":"*****",
    "bindBeneficiaryRequestId": "*****",
    "beneficiaryType": "THIRD_PARTY_COMPANY_BANK_ACCOUNT",
    "countryCode":"DE",
    "currency":"EUR",
    "beneficiaryNick":"NickABC",
    "templateCategory":"LOCAL_TEMPLATE",
    "referenceBeneficiaryId":"2022*****",
    "beneficiaryBankAccount": {
        "bankAccountName":"shen***",
        "bankBIC":"CHASDE*****",
        "bankAccountIBAN":"DE315001051765761*****"
    }
}

响应体范例

copy
{
    "beneficiary": {
        "beneficiaryBankAccount": {
            "bankAccountIBAN": "DE315001051765761*****",
            "bankAccountName": "shen***",
            "bankBIC": "CHASDE*****"
        },
        "beneficiaryNick": "NickABC",
        "beneficiaryToken": "ALIPAYjIIt8*****",
        "beneficiaryType": "THIRD_PARTY_COMPANY_BANK_ACCOUNT",
        "bindBeneficiaryRequestId": "*****",
        "countryCode": "DE",
        "currency": "EUR",
        "referenceBeneficiaryId": "2022****",
        "status": "SUCCESS"
    },
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    }
}

@2024 WorldFirst