bindBeneficiary

2024-01-18 05:32

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."
    }
}