资源

MyBankMatch

通过与您的 Wealthreader 许可证绑定的自有银行所提供的收款人验证（VoP），核实某个 IBAN 是否属于指定的账户持有人。

产品验证中。 我们正在逐步接入银行。如果连接时您的银行不在列表中，请在支持提交工单并注明该金融机构，我们会为其开通；通常需要约 24 小时。

准备连接

拥有包含产品 MY_BANK_MATCH 且有可用配额的有效许可证。
使用已认证的会话和相应许可证打开客户区 · MyBankMatch。
点击连接银行，并在 Wealthreader 托管的窗口中完成认证。令牌化连接会与您的 api_key 关联；银行令牌不会交给浏览器，也不是查询参数。
在客户区刷新状态。如果银行要求重新认证，请使用重新连接。该面板还提供显式的 IBAN/姓名测试以及最近的脱敏查询记录。

发起方使用一次性签名链接和与浏览器绑定的续接状态。如果链接已过期或续接状态丢失，请在客户区重新申请链接。

从后端发送查询

POST https://api.wealthreader.com/my-bank-match/
Content-Type: application/x-www-form-urlencoded

参数	必填	约定
`api_key`	是	有效许可证的 8 位十六进制字符密钥，该许可证需包含 `MY_BANK_MATCH` 且有可用配额。请将其保存在后端。
`iban`	是	SEPA 国家的 IBAN。系统会删除空格、转换为大写，并校验该国家的长度和 mod-97 校验位。
`name`	是	账户持有人姓名：不能为空，须为有效 UTF-8，不含控制字符，最多 140 个字符。系统会去除首尾空白并规范化空格。

不发送 JSON，也不使用 X-API-Key：密钥是表单编码请求体的一部分，与 /entities/ 相同。

curl --request POST 'https://api.wealthreader.com/my-bank-match/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=<SU_API_KEY>' \
  --data-urlencode 'iban=ES9321005707250200257112' \
  --data-urlencode 'name=Wealthreader S.L.'

<SU_API_KEY> 是占位符，不是可用的密钥。此处的 IBAN 和姓名仅用于演示验收请求；本文并未验证它们会产生某个具体结论。该查询可能产生费用：请勿将其作为界面的自动刷新来触发。

MyBankMatch 返回的是银行的结论，不会用本地的姓名相似度计算来替代该响应。它也不会创建、授权或执行付款指令。

解读响应

HTTP 200 表示已获得产品结果，并不表示姓名一定匹配。请先检查 success，再检查 payload.result。

部分匹配的示例（姓名和 SESSION 均为模拟值）：

{
  "success": true,
  "payload": {
    "result": "PARTIAL_MATCH",
    "suggested_name": "TITULAR DE EJEMPLO S.L."
  },
  "statistics": {
    "SESSION": "0000000000000000",
    "execution_time": 0.42,
    "warnings": []
  }
}

statistics.SESSION 用于诊断时标识本次查询，execution_time 以秒为单位。成功的响应不包含 error 对象，也不会返回银行连接的令牌。

`payload.result`	含义	附加字段	是否计费
`MATCH`	银行认为该姓名与账户持有人一致。	无。	是，0.10 EUR。
`PARTIAL_MATCH`	银行返回部分匹配（`CLOSE_MATCH`）。	`suggested_name`：银行告知的真实姓名，而非本地生成的建议。	是，0.10 EUR。
`NO_MATCH`	银行表示该姓名不一致。	无。	是，0.10 EUR。
`NOT_CONFIGURED`	该许可证尚未绑定银行。	`setup_url`。	否。
`REAUTH_REQUIRED`	该连接需要重新认证。	`setup_url` 和 `reason_code`（2xxx 系列的整数）。	否。
`NOT_POSSIBLE`	无法获得可用的结论。不等同于 `NO_MATCH`。	`reason`，一个技术标识符。	否。

部分匹配时，请分别显示用户输入的姓名和 suggested_name；不要静默替换前者。如果在 HTML 中展示，请将其作为文本进行转义。

NOT_CONFIGURED 和 REAUTH_REQUIRED 的设置 URL 为：

https://www.wealthreader.com/clients/#my-bank-match

例如，重新认证时可能返回如下 payload：

{
  "result": "REAUTH_REQUIRED",
  "setup_url": "https://www.wealthreader.com/clients/#my-bank-match",
  "reason_code": 2000
}

reason_code 必须是 2000 到 2999 之间的整数；例如，2000 表示凭据错误。请在客户区重新连接，而不是无限次重复验证。

NOT_POSSIBLE 的原因可能是暂时不可用、银行响应无效、缺少可用的付款方 IBAN 或适配器不可用。请保留 reason 用于诊断，但不要将这些情况视为账户归属确认或不匹配结果。

校验、配额与错误

校验或许可证错误沿用通常的响应结构：success: false、payload、error.code、error.message，以及 statistics（包含 SESSION、耗时和警告）。受控校验返回 HTTP 400；错误消息可能包含诊断信息，不应作为稳定的标识符使用。

`error.code`	原因
`4000`	IBAN 无效：格式、不支持的国家、长度或校验位有误。
`4001`	姓名无效：为空、格式或长度有误。
`2`	请求方法或 `api_key` 错误、许可证未激活、产品未开通或配额已用尽。
`1`	可用性或持久化方面的内部错误。

输入错误和无定论的结果不会消耗计费查询配额。当银行返回 MATCH、PARTIAL_MATCH 或 NO_MATCH 时才会消耗配额；如果另一个并发调用耗尽了配额，则返回额度限制错误，而不是将结果确认为成功。

此方法没有幂等性密钥，也不保证可免费重试。 如果因超时、网络问题或响应体无法解析而丢失响应，您的应用可能无法得知结果及其配额消耗情况。请勿自动重新发送同一查询：请查看客户区的历史记录，如需确认该次尝试，请联系支持。

0.10 EUR 的价格仅适用于约定中的三种确定性结果。按查询计费模式以及已验证绑定会话的排除机制均已实现，但需要预先建立数据库结构，并由运营人员激活和审核计费查询；本页面并不证明该部署已完成。只有经过验证的服务器端关联才能将某个会话排除在凭据/产品的标准计算之外：浏览器的 operation_id 不足以作为依据。缺少此类来源的过期、未审计或历史尝试不会自动豁免，也不保证其他免费计数效果。

本版本的限制

验证使用客户自有的 Santander 个人银行令牌化连接。实际的银行兼容性尚未验证，发布本页面也不代表保证商业可用性。
托管流程支持凭据和 OTP/推送验证、验证方式选择以及有限的栅格二维码。基于脚本、OAuth、CAPTCHA 或多合同的验证尚未实现，会安全地返回错误；您可以在客户区申请新的链接。
该面板需要已认证的会话。加载状态、从银行窗口返回以及刷新历史记录都不会向银行发送验证：只有显式提交表单才会发起可能计费的查询。
请将 api_key 保存在您的服务器上，不要在不必要的集成日志中记录凭据、银行令牌或完整姓名。请使用 SESSION 联系支持，并区分结论、错误和配置状态。

最后更新于 2026-11-08