> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 银行账户核验：无需登录验证账户所有权

> Didit 通过用户输入的账户详情确认银行账户归属于已验证人员，全程无需登录银行。支持 IBAN、sort code、CLABE、CBU、IFSC 等格式。

账户核验根据用户输入的账户信息，确认银行账户是否属于您的工作流已经验证过的用户。无需登录银行，也没有同意授权页面：用户按其所在国家/地区的书写惯例输入账户信息，银行则将账户上的姓名与此前步骤验证的姓名进行核对。

它是两种[银行验证方法](https://docs.didit.me/zh/core-technology/bank-verification/verification-methods.md)之一，与银行登录并列，其方法值为 `account_lookup`。对账单上传和微额打款在两者之后仍作为后备方案，并且用户始终可以[在不使用银行验证的情况下继续](https://docs.didit.me/zh/core-technology/bank-verification/fallbacks.md)。若要直接从您的后端核验账户而无需创建会话（例如在付款前），请使用[账户核验 API](https://docs.didit.me/zh/standalone-apis/bank-account-check.md)。

> [!NOTE]
>
> 银行验证是根据**另一个步骤**已确立的身份来确认谁拥有该账户，因此它本身不能作为身份证明。请在此步骤之前加入身份证件验证、数据库核验、问卷或 `expected_details`。用户无需为该核验输入姓名：Didit 始终比对会话中已经验证的姓名。

## 工作原理

**1. 用户选择其国家/地区**

在银行验证步骤中，用户选择该步骤支持的国家/地区。如果账户核验在当地排在首位，该步骤会以该国家/地区的账户格式打开一个简短表单。如果银行登录排在首位，用户选择**输入您的账户信息**即可进入该表单。

**2. 用户输入其账户信息**

例如 IBAN、分行代码和账号，或者 CLABE。验证流程会根据 API 针对该国家/地区返回的内容生成表单，因此 Didit 日后新增国家/地区时，您无需在己方进行任何更改。

**3. Didit 首先检查格式**

在进行任何计费之前，Didit 会检查每个值：长度、字符、校验位，对于 IBAN 还会检查其是否属于所选国家/地区。未通过的值会被拒绝并指出需要修正的字段。用户在当前界面直接修改，不会消耗尝试次数。

**4. 银行核对账户上的姓名**

Didit 针对会话已验证的姓名执行一次核验。客户端发送的任何其他内容都会被忽略。

**5. 该步骤做出判定**

返回的结果成为账户所有权结果，该步骤的操作会将其转化为最终裁决，方式与银行登录完全相同。

## 该核验支持的地区

覆盖范围按国家/地区划分。在生产环境中，该核验目前在尼日利亚、加纳和肯尼亚运行。Didit 在某国家/地区具备定价路由后，会逐个开放；没有路由的国家/地区则不提供此功能，[银行验证定价](https://docs.didit.me/zh/getting-started/bank-verification-pricing.md)始终显示当前名单。随着时间推移会新增更多国家/地区，且该步骤始终读取最新名单，因此在新增国家/地区时，您无需修改集成代码。

在已覆盖的国家/地区内，该步骤的方法配置决定了用户是否会看到它：

* **步骤顺序。** `bank_method_order` 设置每个国家/地区提供哪些方法以及哪种方法优先。默认值 `["open_banking", "account_lookup"]` 会首先展示银行登录，并将账户核验作为后备选项。
* **国家/地区自定顺序。** `bank_countries` 中某个国家/地区的 `methods` 会覆盖该地区的步骤顺序，例如 `["account_lookup"]` 表示仅使用账户核验，或 `["account_lookup", "open_banking"]` 表示优先使用它。
* **银行服务故障。** 在提供账户核验的国家/地区，它还可以作为银行登录服务降级或故障时的后备方案：在该用户仍可进行账户核验的情况下，该步骤会在请求任何同意授权之前直接切换到账户表单。
* **该核验在 Didit 自有路由上运行。** 在您自有的应用市场提供商（`provider_key`）上运行的步骤，仅在开启 `fallback_to_native` 时才提供此功能。
* **企业账户。** 在企业验证会话中，在 Didit 支持核验企业账户的国家/地区，该核验会将企业账户与已验证的企业进行比对。

有关保存时遵循的规则，请参阅[按国家/地区选择方法](https://docs.didit.me/zh/core-technology/bank-verification/verification-methods.md#按国家/地区选择方式)。

## 用户输入的内容

以下是表单支持的账户格式。这并非覆盖范围名单：某国家/地区是否支持该核验取决于[支持的地区](#该核验支持的地区)，且该步骤始终显示该国家/地区的具体字段。

| 账户格式 | 国家/地区 | 用户输入的内容 |
| - | - | - |
| IBAN | 使用 IBAN 的国家/地区 | 完整的 IBAN，必须属于所选国家/地区 |
| 分行代码和账号 | 英国 | 6 位数字的分行代码和 8 位数字的账号 |
| 路由号码和账号 | 美国 | 9 位数字的 ABA 路由号码和账号 |
| 转接号码和机构号码 | 加拿大 | 8 位数字的转接号码和机构号码（5 位转接号码后接 3 位机构号码）以及账号 |
| BSB 和账号 | 澳大利亚 | 6 位数字的 BSB 和账号 |
| CLABE | 墨西哥 | 18 位数字的 CLABE，其中已标识银行 |
| CBU 或 CVU | 阿根廷 | 22 位数字的 CBU 或 CVU，其中已标识银行 |
| IFSC 和账号 | 印度 | 11 位字符的 IFSC 和账号 |
| NUBAN 和银行代码 | 尼日利亚 | 10 位数字的 NUBAN 以及银行代码或 BIC |
| 账号 | 其他国家/地区 | 账号，以及在该国家/地区需要时的银行代码或 BIC |

在某些国家/地区，表单还会要求填写注册号：适用于企业账户，以及在少数国家/地区适用于所有账户。

在对输入值进行检查前，系统会自动移除空格、破折号和点号，并将英文字母转为大写，因此用户可以完全按照银行打印的格式输入账户信息。

## 启用

新步骤默认提供账户核实，作为银行登录的备选方案。要从此方式开始，或仅提供此方式，请在顺序中将 `account_lookup` 置于首位：

```json theme={null}
{
  "bank_method_order": ["account_lookup", "open_banking"]
}
```

以下设置用于配置该核验：

| 设置 | 对账户核实的影响 |
| - | - |
| `bank_method_order`、`bank_countries.<ISO3>.methods` | 某个国家/地区是否提供该核验，以及它是在银行登录之前还是之后出现。 |
| `bank_countries` | 该核验仅在步骤所提供的国家/地区运行。 |
| `bank_reference_identity` | 用于将账户姓名与其已验证姓名进行比对的步骤。 |
| `bank_account_check_max_attempts` | 用户可进行的核验次数，`1` 到 `5` 次（默认为 `3`）。该计数与银行登录的 `bank_max_attempts` 分开计算。 |
| `bank_account_check_accept_close_match` | 开启（默认）：相近匹配将进入相近匹配确认流程，或执行 `bank_partial_match_action`。关闭：所有相近匹配均视为不匹配。 |
| `bank_name_match_threshold`、`bank_partial_match_floor` | 与银行登录相同的姓名评分区间：达到或高于阈值（默认为 85）为匹配，介于下限（默认为 70）与阈值之间为相近匹配（部分匹配区间）。 |
| `bank_use_provider_score` | 开启（默认）：当核验自带的姓名评分高于 Didit 的评分，或核验返回了评分但未返回户名时，以此评分为准，此时 `ownership.method` 显示为 `provider_only`。关闭：未返回户名的结果视为 `not_verifiable`。 |
| `bank_suggest_holder_name` | 开启（默认）：在返回户名的相近匹配中，用户会看到该姓名并确认是否为其本人，或尝试其他账户。 |

## 结果

### 返回结果的核验

以下每种情况均计费一次，并消耗用户的一次账户核实次数（`bank_account_check_max_attempts`）。在步骤完成前，只要剩余次数大于零，用户就可以使用其他账户重试。结果显示在 `ownership.result` 中，但对于不存在的账户，结果显示在 `connection.reason_code` 中。

| 核验返回结果 | 结果 | 决定逻辑 |
| - | - | - |
| 账户属于已验证的人员 | `match` | 步骤审核通过，除非其包含的其他核验另有判定。 |
| 返回户名的相近匹配 | `partial_match` | 开启 `bank_suggest_holder_name` 时，用户确认姓名或尝试其他账户。确认后步骤以 `bank_partial_match_action` 结束（默认为 `REVIEW`）。 |
| 带有评分但无户名的相近匹配 | `partial_match` | 执行 `bank_partial_match_action`（默认为 `REVIEW`）。`ownership.method` 显示为 `provider_only`。此项需要开启 `bank_use_provider_score`（默认开启）；若关闭，结果为 `not_verifiable`。 |
| 账户属于其他人 | `no_match` | 执行 `bank_no_match_action`（默认为 `DECLINE`）。 |
| 未比对姓名的结果 | `not_verifiable` | 执行 `bank_not_verifiable_action`（默认为 `REVIEW`）。 |
| 该信息对应的账户不存在 | `ACCOUNT_NOT_FOUND` | 只要剩余次数大于零，用户就可以尝试其他账户。 |

若关闭 `bank_account_check_accept_close_match`，上述两种相近匹配都将转为 `no_match`，原因代码为 `OWNER_NAME_MISMATCH`：系统绝不会要求用户确认姓名，并由 `bank_no_match_action` 决定结果。无论何种情况，银行登录均保留其相近匹配逻辑。

一旦用户用尽所有账户核实次数，以及在支持银行登录的国家/地区用尽所有银行登录尝试次数，且未成功连接，只要步骤仍提供流水上传且尚有剩余次数，步骤便保持开启状态：参见[流水上传](https://docs.didit.me/zh/core-technology/bank-verification/fallbacks.md#对账单上传)。当没有其他途径可用时，步骤以 `bank_attempts_exhausted_action` 结束（默认为 `DECLINE`），除非先前的尝试已得出结论（例如姓名不匹配）。此时该判定仍然有效。

### 绝不计费的结果

以下情况均不消耗核验次数。每种情况都会显示在 `connection.reason_code` 中。

| 发生情况 | 原因代码 | 后续处理 |
| - | - | - |
| 输入的账户信息被 Didit 的格式校验或银行拒绝 | `INVALID_ACCOUNT_INPUT`（尝试保持开启状态） | 提示用户需要修正的字段并进行修改。 |
| 核验服务当前不可用 | `PROVIDER_UNAVAILABLE` | 用户可以重试。 |
| 会话中没有可供比对的已验证姓名 | `REFERENCE_IDENTITY_MISSING` | 核验绝不运行。步骤以 `bank_reference_identity_missing_action` 结束（默认为 `REVIEW`）。 |

### 在决策中

会话决策在 `bank_verifications[]` 下列出该步骤。账户完成评估后，`method` 显示为 `account_lookup`。在未对账户进行评估时，`method` 和 `ownership` 为 `null`，且 `connection.reason_code` 会说明原因，例如 `ACCOUNT_NOT_FOUND`、`PROVIDER_UNAVAILABLE` 或 `REFERENCE_IDENTITY_MISSING`。

该核验无需选择银行，因此 `connection.institution_id`、`connection.institution_name` 和 `connection.oauth` 均为 `null`，而 `connection.institution_country` 为用户选择的国家/地区。步骤完成后，Didit 不会保留对账户的访问权限，因此以匹配结束的核验显示为 `connection.status: revoked`，且 `reason_code: VERIFICATION_COMPLETED`。结果本身会保留在会话中。

账户核实不会读取余额、交易记录或收入。当步骤要求获取这些信息时，`financial_data.not_collected` 会列出它们；参见[财务数据需要银行登录](https://docs.didit.me/zh/core-technology/bank-verification/verification-methods.md#财务数据需要银行登录)。

```json theme={null}
{
  "bank_verifications": [
    {
      "status": "Approved",
      "method": "account_lookup",
      "connection": {
        "status": "revoked",
        "institution_id": null,
        "institution_name": null,
        "institution_country": "NGA",
        "oauth": null,
        "attempts": 1,
        "reason_code": "VERIFICATION_COMPLETED"
      },
      "ownership": {
        "result": "match",
        "method": "exact"
      },
      "financial_data": {
        "balances": null,
        "transactions": null,
        "income": null,
        "categorization": null,
        "not_collected": []
      },
      "billing": {
        "route": "native",
        "billed": true,
        "marketplace_fee": null,
        "usage_type": "bank_verification"
      }
    }
  ]
}
```

该示例仅展示本页面讨论的字段。评估账户后，读取 `method` 即可区分账户核实与银行登录：该字段专门用于此目的。

### 在工作流规则和报告中

* **分支与状态规则：**`bank.method` 为 `account_lookup`（规则构建器中为 **账户核实**），且 `bank.reason_code` 可以是 `ACCOUNT_NOT_FOUND`。
* **会话 PDF 报告：** **验证方式** 行显示为 **账户核实**。

## 定价

每次返回结果的核查均计为一次 Bank Verification 费用：匹配、高度相似、不匹配、无法验证的账户以及未找到的账户均会计费。核查前被拒绝的值、不可用的核查以及没有已核验姓名可供比对的会话均不会计费。价格按国家/地区设定：请参阅 [Bank Verification 定价](https://docs.didit.me/zh/getting-started/bank-verification-pricing.md)。

账户核查本身就是一种独立付费方式，绝非后备方案：`bank_fallback_used_action` 不会对其触发。在完成一次计费核查后，如果该步骤启用了小额存款和对账单上传且所在国家/地区支持这些功能，则在同一会话中包含它们，不收取额外费用。

## 在沙盒中测试

在沙盒应用中，核查在模拟服务上运行，不会产生任何计费。沙盒在所有国家/地区按步骤设置的顺序提供这两种方式：在默认顺序下，选择**输入您的账户信息**即可运行核查，或者将 `bank_method_order` 设置为 `["account_lookup", "open_banking"]` 直接开始该核查。

用户输入的账户（IBAN，否则为账号）的最后四位字符决定了返回的响应结果。任何其他结尾均与已核验姓名匹配。

| 结尾 | 响应结果 |
| - | - |
| `0001` | 指明账户持有人的高度相似匹配：系统会要求用户确认姓名。当 `bank_account_check_accept_close_match` 关闭时，视为不匹配。 |
| `0002` | 未指明持有人姓名的高度相似匹配：由 `bank_partial_match_action` 决定。当 `bank_use_provider_score` 关闭时，响应结果为 `not_verifiable`；当 `bank_account_check_accept_close_match` 关闭时，视为不匹配。 |
| `0003` | 不匹配：该账户属于其他人。计费一次核查。 |
| `0004` | 已响应但未比对姓名（`not_verifiable`）。计费一次核查。 |
| `0005` | 核查不可用（`PROVIDER_UNAVAILABLE`）。可免费重试。 |
| `0006` | 不存在具有这些信息的账户（`ACCOUNT_NOT_FOUND`）。计费一次核查。 |
| `0009` | 按输入内容被拒绝：系统要求用户更正该字段。该次尝试保持开启状态。 |

沙盒会将每次返回响应的核查记录为免费用量，以便您了解生产环境会话会对哪些核查计费。

IBAN、CLABE 和 CBU 包含校验码，因此您不能仅仅更改其最后四位字符。请使用以下能够通过所有格式校验的值：

> [tab] 德国 (IBAN)
>
> | 响应结果 | IBAN |
> | - | - |
> | 匹配 | `DE43123456789012345678` |
> | `0001` | `DE62123456789012340001` |
> | `0002` | `DE35123456789012340002` |
> | `0003` | `DE08123456789012340003` |
> | `0004` | `DE78123456789012340004` |
> | `0005` | `DE51123456789012340005` |
> | `0006` | `DE24123456789012340006` |
> | `0009` | `DE40123456789012340009` |

> [tab] 英国
>
> 分行代码 `123456`，搭配：
>
> | 响应结果 | 账号 |
> | - | - |
> | 匹配 | `12345678` |
> | `0001` | `12340001` |
> | `0002` | `12340002` |
> | `0003` | `12340003` |
> | `0004` | `12340004` |
> | `0005` | `12340005` |
> | `0006` | `12340006` |
> | `0009` | `12340009` |

> [tab] 美国
>
> 路由号 `021000021`，搭配：
>
> | 响应结果 | 账号 |
> | - | - |
> | 匹配 | `000123456789` |
> | `0001` | `000123450001` |
> | `0002` | `000123450002` |
> | `0003` | `000123450003` |
> | `0004` | `000123450004` |
> | `0005` | `000123450005` |
> | `0006` | `000123450006` |
> | `0009` | `000123450009` |

> [tab] 墨西哥 (CLABE)
>
> | 响应结果 | CLABE |
> | - | - |
> | 匹配 | `002010077777777771` |
> | `0001` | `002010077777780001` |
> | `0002` | `002010077777750002` |
> | `0003` | `002010077777720003` |
> | `0004` | `002010077777790004` |
> | `0005` | `002010077777760005` |
> | `0006` | `002010077777730006` |
> | `0009` | `002010077777740009` |

> [tab] 阿根廷 (CBU)
>
> | 响应结果 | CBU |
> | - | - |
> | 匹配 | `2850590940090418135201` |
> | `0001` | `2850590940090418160001` |
> | `0002` | `2850590940090418170002` |
> | `0003` | `2850590940090418180003` |
> | `0004` | `2850590940090418190004` |
> | `0005` | `2850590940090418100005` |
> | `0006` | `2850590940090418110006` |
> | `0009` | `2850590940090418140009` |

> [tab] 印度
>
> IFSC `ALLA0211480`，搭配：
>
> | 响应结果 | 账号 |
> | - | - |
> | 匹配 | `123456789007` |
> | `0001` | `123456780001` |
> | `0002` | `123456780002` |
> | `0003` | `123456780003` |
> | `0004` | `123456780004` |
> | `0005` | `123456780005` |
> | `0006` | `123456780006` |
> | `0009` | `123456780009` |

[Account check API](https://docs.didit.me/zh/standalone-apis/bank-account-check.md) 针对沙盒密钥会根据相同的结尾返回响应结果，且无需会话。

有关沙盒应用总体工作机制的说明，请参阅[沙盒测试](https://docs.didit.me/zh/integration/sandbox-testing.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.