简介
通过在创建或更新收款人时验证收款人的银行账户信息，可以改善客户体验并减少在英国支付错误的发生。
此指南旨在帮助您通过 Verify Beneficiary Account API 验证本地 GBP 支付的收款人银行账户信息，这是我们的收款人确认服务。验证收款人有助于避免付款发送到错误的账户，在打击欺诈和诈骗方面增加了额外保护。
对于采用赞助和财政模型且与 The CurrencyCloud Limited 签订合同的客户，如果您向终端客户提供本地 GBP 支付服务，则必须集成此 API。
测试版通知：
请注意，此 API 目前处于测试阶段。一些响应代码和原因可能会在此期间发生变化。在测试期间，实施任何可能导致中断的更改之前，我们始终会至少提前 10 天发出通知。
这是什么？
Verify Beneficiary Account API 可以用来验证收款人的银行账户号码，在某些市场中可检查提供的个人或公司名称。
如何操作？
- 终端客户输入收款人的账户详情。
- Currencycloud 将此请求转发给收款人的银行或与数据集进行交叉验证。
- 对于英国市场，我们会返回一个响应，显示验证结果，包含以下字段：
answer、actual_name、reason_code、reason和reason_type。
谁是终端客户？验证需要在哪里进行？
在大多数情况下，终端客户是我们签约并提供受监管支付服务的个人或企业。要求是终端客户必须能够收到验证响应，然后才能继续在您的界面上创建收款人。例如，如果您是一个应付账款平台，那么使用该平台的终端客户必须能够在创建收款人并提交发票付款之前验证收款人详情。
然而，在某些使用场景中，终端客户可能无法创建收款人，但您仍然在技术上需要提供此服务。例如财富科技平台，它会自动填充用于支付的相同账户详情。如果以上情况适用于您，请咨询您的客户成功经理和解决方案顾问，我们将与您合作，了解您的具体使用场景。
可用性
我们目前在英国提供测试版 Verify Beneficiary Account API。未来我们将支持更多国家/地区。如需了解更多信息，请联系客户支持或您的客户成功经理。
第 1 步：登录
请参阅验证指南，获取开始新 API 会话的说明。确保您的联系人 ID 已启用，以便在我们的演示环境中访问此产品。
第 2 步：验证收款人
请求
要验证英国收款人的银行账户信息，请向 Verify Beneficiary Account /v2/beneficiaries/account_verification 端点发出 POST 请求。
POST /v2/beneficiaries/account_verification
请求正文需包含以下参数：
Content-Type: multipart/form-data
| 参数名称 | 参数类型 | 必填 | 示例值 | 备注 |
|---|---|---|---|---|
| payment_type | 表单数据 | 否 | regular | "priority"（Swift 网络）或 "regular"（本地） |
| bank_country | 表单数据 | 是 | GB | 收款人银行账户所在国家/地区的两个字母代码 |
| currency | 表单数据 | 是 | GBP | 三个字母的货币代码 | 汇款至收款人银行账户所用的货币 |
| account_number | 表单数据 | 是 | 73515966 | 英国银行账号 |
| beneficiary_entity_type | 表单数据 | 是 | individual | "individual" 或 "company"。如果为个人，则 'beneficiary_first_name' 和 'beneficiary_last_name' 是必填项。如果为公司，则 'beneficiary_company_name' 是必填项。 |
| beneficiary_company_name | 表单数据 | 否 | Sousa Ltd | 当实体为 "company" 时为必填项。 |
| beneficiary_first_name | 表单数据 | 否 | Ricardo | 当实体为 "individual" 时为必填项。 |
| beneficiary_last_name | 表单数据 | 否 | Sousa | 当实体为 "individual" 时为必填项。 |
| routing_code_type_1 | 表单数据 | 否 | sort_code | 本地支付路由系统，例如 sort_code、aba、bsb_code institution_no、bank_code、branch_code、clabe、cnaps |
| routing_code_value_1 | 表单数据 | 否 | 015561 | routing_code_type_1 的路由编码。 |
| routing_code_type_2 | 表单数据 | 否 | 本地支付路由系统 | |
| routing_code_value_2 | 表单数据 | 否 | routing_code_type_2 的路由编码 | |
| bic_swift | 表单数据 | 否 | BIC/Swift Code | |
| iban | 表单数据 | 否 | IBAN（国际银行账户号码） | |
| secondary_reference_data | 表单数据 | 否 | 无法通过银行代码和账号唯一标识的终端客户账户，而是依赖其支付服务提供商 (PSP) 通过 SRD 为其账户入账，即在付款的参考字段中使用进一步的唯一标识符。 |
示例请求：
{
"payment_type": "regular",
"bank_country":"GB",
"currency":"GBP",
"account_number":"73515966",
"beneficiary_entity_type": "individual",
"beneficiary_company_name": null,
"beneficiary_first_name":"Ricardo",
"beneficiary_last_name":"Sousa",
"routing_code_type_1": "sort_code",
"routing_code_value_1":"015561",
"routing_code_type_2": null,
"routing_code_value_2": null,
"bic_swift": null,
"iban": null,
"secondary_reference_data": null
}
响应
请注意，您必须禁用您的界面数据缓存功能，以确保终端客户无法在未进行进一步的收款人确认请求的情况下，访问之前通过收款人确认请求获取的数据。
示例响应
200
{
"answer": "full_match",
"actual_name":"Ricardo Sousa",
"reason_code":"AV100",
"reason":"Full match.",
"reason_type": "okay"
}
200
{
"answer": "close_match",
"actual_name":"Ricardo Sous",
"reason_code":"AV300",
"reason":"String is a close match to the account name.",
"reason_type": "warning"
}
JSON 响应正文中包含以下参数：
| 参数名称 | 数据类型 | 示例值 | 描述 |
|---|---|---|---|
| answer | 字符串 | full_match | 验证是否产生匹配的指示器。可能的值包括 'full match'、'close match' 或 'no match' |
| actual_name | 字符串 | Ricardo Sousa | 账户持有人的实际姓名。当 reason_code 为 AV100、AV300、AV301 或 AV302 时存在。 |
| reason_code | 字符串 | AV100 | 编码原因。当答案为 'full match'、'close match' 或 'no match' 时存在。 |
| reason | 字符串 | Full match | Reason_code 的元数据。仅在 reason_code 存在时填写。值对应于 reason_code 的描述。 |
| reason_type | 字符串 | okay | 原因的元数据。仅在 reason_code 存在时填写。类型对应于客户端 UI 中建议的警告消息要求。可能的值为 'okay'、'rejected' 和 'warning'。 |
有关在 UI 中反映 API 响应的指南
当集成我们的 Verify Beneficiary Account API 时，请务必有效处理各种响应，以提供无缝的用户体验。以下是在您的界面中实现每个响应的建议，包括文案和用户体验处理建议。
请注意：如果您是与 The Currency Cloud Limited 签订合同的“赞助”或“财政”模型客户，那么您必须将收款人账户验证步骤作为创建英国收款人流程的一部分，然后再通过我们的创建支付 API 向收款人支付。
1.AV100（完全匹配）
请求：
{
"payment_type": "regular",
"bank_country":"GB",
"currency":"GBP",
"account_number":"73515966",
"beneficiary_entity_type": "individual",
"beneficiary_company_name": null,
"beneficiary_first_name":"Ricardo",
"beneficiary_last_name":"Sousa",
"routing_code_type_1": "sort_code",
"routing_code_value_1":"015561",
"routing_code_type_2": null,
"routing_code_value_2": null,
"bic_swift": null,
"iban": null,
"secondary_reference_data": null
}
响应：
200
{
"answer": "full_match",
"actual_name":"Ricardo Sousa",
"reason_code":"AV100",
"reason":"Full match.",
"reason_type": "okay"
}
API 原因：完全匹配
描述：收款人的银行已确认全名和账户匹配。
处理：终端客户可以继续创建收款人。
UI 建议：
2.AV300（接近匹配）
请求：
{
"payment_type": "regular",
"bank_country":"GB",
"currency":"GBP",
"account_number":"73515966",
"beneficiary_entity_type": "individual",
"beneficiary_company_name": null,
"beneficiary_first_name":"Ricardo",
"beneficiary_last_name":"Sous",
"routing_code_type_1": "sort_code",
"routing_code_value_1":"015561",
"routing_code_type_2": null,
"routing_code_value_2": null,
"bic_swift": null,
"iban": null,
"secondary_reference_data": null
}
响应：
200
{
"answer": "close_match",
"actual_name":"Ricardo Sousa",
"reason_code":"AV300",
"reason":"String is a close match to the account name.",
"reason_type": "warning"
}
API 响应：AV300
描述：此为接近匹配。显示一条消息，强调错误及继续创建的风险。实际 account_name 将在响应中提供。
处理：在接近匹配的情况下，向终端客户显示 actual_name。考虑提供号召性用语或按钮来鼓励用户提交正确的详细信息。这样可以减少认知负担，使他们更容易调整选择。
在接近匹配的情况下，重要的是要清楚地解释问题和解决方案。如果终端客户决定继续操作，则显示一个对话框，再次提醒他们操作是在自愿和自担风险的情况下进行的。
UI 建议：
3.AV201（不匹配）
请求：
{
"payment_type": "regular",
"bank_country":"GB",
"currency":"GBP",
"account_number":"11235813",
"beneficiary_entity_type": "individual",
"beneficiary_company_name": null,
"beneficiary_first_name":"Ricardo",
"beneficiary_last_name":"Smith",
"routing_code_type_1": "sort_code",
"routing_code_value_1":"314159",
"routing_code_type_2": null,
"routing_code_value_2": null,
"bic_swift": null,
"iban": null,
"secondary_reference_data": null
}
响应：
200
{
"answer": "no_match",
"actual_name": null,
"reason_code":"AV201",
"reason":"String does not match the account name.",
"reason_type": "rejected"
}
API 响应：AV201
响应：字符串与账户名称不匹配。
处理：不匹配。显示一条负面通知，强调错误。actual_name 不会在响应中提供。创建一个按钮，让终端客户选择编辑账户详细信息或保留他们输入的内容。
在不匹配的情况下，重要的是清楚地解释问题。如果终端客户决定继续操作，则显示一个对话框，再次提醒他们操作是在自愿和自担风险的情况下进行的。
UI 建议：
原因代码
本节提供了完整的原因代码列表，并附有在用户界面中体现这些原因代码的建议。
我们的文案和处理建议以 Currencycloud Direct 平台的风格和语气为基础。虽然不必完全匹配，但您的集成应该与其紧密相似，以保持一致的用户体验。
成功响应 (HTTP 200)
| 应答 | 原因 编码 |
原因 | 原因类型 | 建议文案 | 如何处理 |
| full_match | AV100 | 完全匹配 | Okay |
 收款人详细信息已确认已确认收款人的详细信息完全匹配。请继续创建收款人。 [返回] [取消] [创建收款人] |
向终端客户显示一条正面通知，表示验证成功。 |
| no_match | AV200 | 指定账号无账户。 | 已拒绝 |
 无法确认账户详细信息提供的收款人账号和银行代码与记录不匹配。请检查您输入的信息，必要时点击“返回”进行更新，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人] 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 3.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。 4.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
| no_match | AV201 | 字符串与账户名称不匹配。 | 已拒绝 |
收款人名称不匹配 您提供的收款人名称与记录中的名称不匹配。请检查您输入的信息，必要时点击“返回”进行更新，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人] 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 3.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。 4.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
| no_match | AV202 AV203 AV204 AV205 |
无法检查账户详细信息。 | 已拒绝 |
无法检查提供的详细信息 无法检查您提供的收款人详细信息。请检查您输入的信息，必要时点击“返回”进行更新，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人] 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 3.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。 4.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
| no_match | AV206 | 无效的次级终端客户参考数据。 | 已拒绝 |
提供的详细信息不匹配 您提供的收款人参考详细信息与记录不匹配。请检查您输入的信息，必要时点击“返回”进行更新，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人] 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 3.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。 4.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
| no_match | AV207 | 无法检查账户详细信息。 | 已拒绝 | 使用测试包中未包含的数据会导致我们的演示环境中出现此响应。如果在真实环境中发生此情况，请报告至 support@currencycloud.com。 | |
| close_match | AV300 | 字符串与账户名称接近匹配 | 警告 |
 收款人名称不正确您为收款人提供的详细信息与记录中的信息接近匹配，但名称为 '[actual_name]'。请检查您输入的信息，必要时点击“返回”，将收款人名称更新为 '[actual_name]'，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人]（在选择之前禁用） 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.将提供 actual_name。围绕 [actual_name] 编辑提供的文案。3.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 4.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。5.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
| close_match | AV301 | 字符串与账户名称接近匹配。账户类型为企业账户，但请求中指示的是个人账户。 | 警告 |
公司名称不正确 您为收款人提供的详细信息与记录中的信息接近匹配，但公司名称为 '[actual_name]'。请检查您输入的信息，必要时点击“返回”，将公司名称更新为 '[actual_name]'，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人]（在选择之前禁用） 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.将提供 actual_name。围绕 [actual_name] 编辑提供的文案。3.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 4.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。5.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
| close_match | AV302 | 字符串与账户名称接近匹配。账户类型为个人账户，但请求中指示的是企业账户。 | 警告 |
收款人名称不正确 您为收款人提供的详细信息与记录中的信息接近匹配，但名称为 '[actual_name]'。请检查您输入的信息，必要时点击“返回”，将收款人名称更新为 '[actual_name]'，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人]（在选择之前禁用） 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.将提供 actual_name。围绕 [actual_name] 编辑提供的文案。3.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 4.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。5.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
| close_match | AV303 | 字符串与账户名称匹配，但账户类型为企业账户，而请求中指示的是个人账户。 | 警告 |
收款人类型不正确 您为收款人提供的详细信息与记录中的信息接近匹配，但收款人被识别为公司，而非个人。请检查您输入的信息，必要时点击“返回”，将收款人类型更新为 'Company'，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人] 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 3.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。 4.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
| close_match | AV304 | 字符串与账户名称接近匹配，但账户类型为个人账户，而请求中指示的是企业账户。 | 警告 |
收款人类型不正确 您为收款人提供的详细信息与记录中的信息接近匹配，但其被识别为个人，而非公司。请检查您输入的信息，必要时点击“返回”，将收款人类型更新为 'Individual'，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人] 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 3.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。4.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
| close_match | AV305 | 账户已切换到不同的组织。 | 警告 |
账户已切换 您为收款人提供的详细信息与记录中的信息接近匹配，但账户已切换到不同的组织。请检查您输入的信息，必要时点击“返回”进行更新，或者如果您确定信息正确，请点击“创建收款人”。 [返回] [取消] [创建收款人] 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
1.显示一条负面通知，强调错误。 2.创建一个按钮，供终端客户选择“返回”、“取消”或“创建收款人”。 3.如果用户点击/点按“返回”，则必须提交一个新的 API 请求来检查新的详细信息。 4.如果用户点击/点按“创建收款人”，则终端客户应通过对话框接收二次警告。 |
技术错误
HTTP 503 - 服务不可用
| 错误代码 | 错误 原因 |
所需文案 | 如何处理 |
| service_unavailable | 服务暂时不可用 |
无法检查提供的详细信息 此时无法检查您提供的收款人详细信息。请稍后再次尝试创建收款人，或者如果您确定详细信息正确无误，请点击“创建收款人”。 [返回] [取消] [创建收款人] 您确定要继续吗？ 向此人或此企业付款可能导致您的资金被汇入错误账户。我们可能无法为您追回这笔资金。 [取消] [仍要继续] |
连接失败 1.显示一条负面通知，强调问题。 2.在将错误返回给用户之前引入内部重试机制。 3.如果用户点击/点按“返回至详细信息”，终端客户将返回到收款人创建界面。 4.需要提交新的请求来检查新的详细信息。 5.如果用户点击/点按“仍要继续”，则终端客户应接收到二次警告。 |
HTTP 400 - 错误请求
由于终端客户不应触发这些验证，所需文案和处理要求不适用于 HTTP 400 错误。
| 错误代码 | 错误原因 |
|---|---|
| invalid_bank_country | 银行国家/地区不支持 |
| invalid_field_bank_country | bank_country 必须匹配 "^[A-Z]{2}$" |
| invalid_field_account_number | account_number 必须匹配 ^[0-9]{1,8}$ |
| invalid_field_routing_code_value_1 | routing_code_value_1 必须匹配 ^[0-9]{6}$ |
| invalid_field_beneficiary_type | beneficiary_entity_type 必须为 'individual' 或 'company'。 |
| expect_individual_names_only | 当 beneficiary_entity_type 为个人时，不得提供 beneficiary_company_name。 |
| expect_company_name_only | 当 beneficiary_entity_type 为公司时，不得提供 beneficiary_first_name 和 beneficiary_last_name。 |
| missing_individual_names | 当 beneficiary_entity_type 为个人时，必须提供 beneficiary_first_name 和 beneficiary_last_name。 |
| missing_company_name | 当 beneficiary_entity_type 为公司时，必须提供 beneficiary_company_name。 |
第 3 步：创建或更新收款人
成功验证详细信息后，您可以使用 Beneficiaries API 设置新的收款人记录或更新现有记录。向 Create Beneficiary /v2/beneficiaries/create 端点发出 POST 请求以创建新的收款人，或向 Update Beneficiary /v2/beneficiaries/{id} 端点发出 POST 请求以更新现有收款人。
请注意，如果在账户验证过程中出现 'close match'，并且用户从响应中选择了账户名称，则在创建或更新收款人时需要使用这些详细信息。
如果收款人成功创建或更新，则响应消息将包含在您的 Currencycloud 账户中记录的收款人完整详细信息。
请注意收款人的唯一 ID (id)。您需要此 ID 才能向收款人付款。
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "aea097c2-39e4-49b5-aaa6-c860ca55ca0b",
"bank_account_holder_name":"Acme GmbH",
"name":"Acme GmbH",
"email": null,
"payment_types": [
"regular"
],
"beneficiary_address": [],
"beneficiary_country":"DE",
"beneficiary_entity_type": null,
"beneficiary_company_name": null,
"beneficiary_first_name": null,
"beneficiary_last_name": null,
"beneficiary_city": null,
"beneficiary_postcode": null,
"beneficiary_state_or_province": null,
"beneficiary_date_of_birth": null,
"beneficiary_identification_type": null,
"beneficiary_identification_value": null,
"bank_country":"DE",
"bank_name":"Test Bank Plc",
"bank_account_type": null,
"currency":"EUR",
"account_number": null,
"routing_code_type_1": null,
"routing_code_value_1": null,
"routing_code_type_2": null,
"routing_code_value_2": null,
"bic_swift":"COBADEFF",
"iban": "[Sensitive data redacted]",
"default_beneficiary": "false",
"creator_contact_id":"1993263d-be07-42d4-b75b-ae4ea18bcb6c",
"bank_address": [],
"created_at":"2021-02-02T11:52:23+00:00",
"updated_at":"2021-02-02T11:52:23+00:00",
"beneficiary_external_reference": null
}
第 4 步：开发您的用户旅程
将 Verify Beneficiary Account API 集成到您的应用程序时，建议采用以下最佳实践：
- 清晰的消息传递：确保每则响应附带的消息简洁、信息丰富且用户友好。
- 视觉反馈：使用图标、颜色和消息横幅等视觉元素，向用户提供清晰的反馈。
- 错误处理：实施强大的错误处理机制，妥善处理来自 Verify Beneficiary Account API 的意外响应或错误。
- 可访问性：设计 UI 时要确保所有用户均可访问，确保响应消息可感知且易于理解。
遵循这些指南，您可以无缝地将 Verify Beneficiary Account API 的响应与您的界面集成，为用户在验证收款人详细信息时提供顺畅且直观的体验。
示例如下：
