> ## 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.

# 南非银行账户持有人验证 API

> Didit 提供南非银行账户持有人验证，通过南非权威数据库查询完成核验。按次计费，起价 $0.40，无需合同，也无最低消费。

确认南非银行账户归指定持有人所有，依据是银行间账户持有人核验服务。Didit 通过 `POST /v3/database-validation/` 提供此服务，帮助您将提交的数据与权威数据源进行核验，并获得标准化的匹配结果。

## 覆盖范围

* **覆盖范围：** —
* **国家：** 南非
* **服务 ID：** `zaf_bank_account_holder`
* **数据领域：** 金融
* **类别：** 银行业务

## 输入

| 字段 | 必填 | 示例 |
| - | -: | - |
| `national_id` | 是 | `8708150847085` |
| `bank_account_number` | 是 | `1234567890` |
| `bank_name` | 是 | `ABSA` |
| `account_type` | 否 | `current` |
| `first_name` | 否 | `John` |
| `last_name` | 否 | `Doe` |
| `initials` | 否 | `JD` |
| `email` | 否 | `john.doe@example.com` |
| `phone_number` | 否 | `+15550101000` |
| `vendor_data` | 否 | `user-1234` |

* **必填输入：** `national_id`、`bank_account_number`、`bank_name`
* **可选输入：** `account_type`、`first_name`、`last_name`、`initials`、`email`、`phone_number`、`vendor_data`
* **同意：** 必填
* **工作流可用性：** 可在工作流中使用，需进行字段映射
* **覆盖范围：** —
* **价格：** 每次成功查询 \$0.40

在工作流中，`bank_account_number` 和 `bank_name` 不会印在身份证件上，因此没有任何步骤能单独生成它们。请从问卷答案、Document AI 提取字段，或您在创建会话时发送的值中收集这些数据，并在数据库核验步骤中分别映射。在完成映射之前，工作流编辑器会将此服务显示为禁用，并指出缺少的输入；运行时如果缺少输入，该检查会在任何查询之前跳过，因此您永远不会为无法查询的数据库付费。

## 请求体参数

**issuing\_state** `string` *required* (default: ZAF)

此数据库服务的 ISO 3166-1 alpha-3 国家代码。

示例：`ZAF`

**services** `string` *required* (default: zaf\_bank\_account\_holder)

包含此服务 ID 的数组。指定该服务可将请求限定为仅针对这一数据库。

示例：`zaf_bank_account_holder`

**consent** `boolean` *required* (default: true)

终端用户对此服务的明确同意。

示例：`true`

**national\_id** `string` *required* (default: 8708150847085)

此服务的国民身份号码。

示例：`8708150847085`

**bank\_account\_number** `string` *required* (default: 1234567890)

此数据库服务所需的 `bank_account_number` 值。

示例：`1234567890`

**bank\_name** `string` *required* (default: ABSA)

此数据库服务所需的 `bank_name` 值。

示例：`ABSA`

**account\_type** `string` (default: current)

此数据库服务所需的 `account_type` 值。

示例：`current`

**first\_name** `string`

需要核验的名字。

示例：`John`

**last\_name** `string` (default: Doe)

需要核验的姓氏。

示例：`Doe`

**initials** `string` (default: JD)

此数据库服务所需的 `initials` 值。

示例：`JD`

**email** `string`

电子邮箱地址。

示例：`john.doe@example.com`

**phone\_number** `string`

此数据库服务所需的 `phone_number` 值。

示例：`+15550101000`

**vendor\_data** `string` (default: user-1234)

您为此用户提供的稳定用户标识，例如您内部的用户 ID。Didit 使用它将独立检查关联到同一终端用户，并减少重复检测的干扰。

示例：`user-1234`

## 输入规则与验证说明

* `account_type` 必须是南非 AVS 账户类型之一：`current`、`savings`、`transmission`、`subscriptionShare`、`notKnown`。匹配不区分大小写。如果您不知道账户类型，请省略该字段。此时 Didit 会发送 `notKnown`，账户类型交叉核验会被报告为未确认，而不会导致请求失败。

## 调用方法

```bash cURL theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=ZAF" \
  -F "services=zaf_bank_account_holder" \
  -F "vendor_data=user-1234" \
  -F "consent=true" \
  -F "national_id=8708150847085" \
  -F "bank_account_number=1234567890" \
  -F "bank_name=ABSA" \
  -F "account_type=current" \
  -F "last_name=Doe" \
  -F "initials=JD"
```

每次成功调用都会返回 HTTP `200`。**`outcome_code`** 字段会告诉您实际发生了什么，例如区分真实的生物识别不匹配（`BIOMETRIC_NO_MATCH`）与无法读取的自拍照（`BIOMETRIC_IMAGE_UNUSABLE`）。显示的 `status` 是默认功能状态；您配置的[部分匹配 / 不匹配操作](https://docs.didit.me/zh/core-technology/database-validation/database-validation-warnings.md)可以覆盖它。

**`MATCH`**：注册表已确认身份，且所有核对字段均匹配。

```json 200 OK — MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Approved",
  "issuing_state": "ZAF",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "zaf_bank_account_holder",
      "service_name": "South Africa - Bank Account Holder Verification",
      "source_data": {
        "accepts_credits": true,
        "accepts_debits": true,
        "account_found": true,
        "account_number_length_valid": true,
        "account_open": true,
        "account_type_match": true,
        "id_match": true,
        "identification_number": "SAMPLE-ID-12345",
        "initials_match": true,
        "surname_match": true
      },
      "validation": {
        "full_name": "full_match",
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`PARTIAL_MATCH`**：找到了证件号码，但一个或多个个人字段（通常是姓名或出生日期）未完全匹配。

```json 200 OK — PARTIAL_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "ZAF",
  "match_type": "partial_match",
  "validations": [
    {
      "outcome_code": "PARTIAL_MATCH",
      "service_id": "zaf_bank_account_holder",
      "service_name": "South Africa - Bank Account Holder Verification",
      "source_data": {
        "accepts_credits": true,
        "accepts_debits": true,
        "account_found": true,
        "account_number_length_valid": false,
        "account_open": true,
        "account_type_match": true,
        "id_match": true,
        "identification_number": "SAMPLE-ID-12345",
        "initials_match": true,
        "surname_match": false
      },
      "validation": {
        "full_name": "partial_match",
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`NO_MATCH`**：注册表未返回与所提交数据匹配的结果。

```json 200 OK — NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "ZAF",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "NO_MATCH",
      "service_id": "zaf_bank_account_holder",
      "service_name": "South Africa - Bank Account Holder Verification",
      "source_data": {
        "accepts_credits": false,
        "accepts_debits": false,
        "account_found": false,
        "account_number_length_valid": false,
        "account_open": false,
        "account_type_match": false,
        "id_match": false,
        "identification_number": "NO_MATCH",
        "initials_match": false,
        "surname_match": false
      },
      "validation": {
        "identification_number": "no_match"
      }
    }
  ]
}
```

## 返回数据

`source_data` 中实际返回的字段取决于登记库返回的内容。`zaf_bank_account_holder` 当前生成的示例记录了以下标准化结构：

* `accepts_credits`
* `accepts_debits`
* `account_found`
* `account_number_length_valid`
* `account_open`
* `account_type_match`
* `id_match`
* `identification_number`
* `initials_match`
* `surname_match`

## 定价与 SLA

南非银行账户持有人验证查询仅在 Didit 从核验数据源收到确定结果时计费。

* **单次调用价格**：\$0.40 USD。
* **计费方式**：按成功的查询计费。当登记库无法访问、缺少必填字段，或请求在到达数据源之前被拒绝时，不收取费用。
* **延迟**：典型 p95 小于 2 秒。
* **可用性**：Didit 侧每季度 99.9%；下游数据源的可用性因国家和数据集而异。

## MATCH 代表什么

账户持有人验证（AVS）是一组是或否的交叉核对，而不是记录查询。数据源从不返回姓名、证件号码或账户余额。它接收您发送的信息，将其与银行为该账户持有的信息进行比对，并以标志位回应每项比对。`source_data` 包含这些标志位：

* **`account_found`**：银行有一个账号为此号码的账户。该值为 `false` 时，其他所有字段均无意义。
* **`account_open`**：账户处于开立状态。账户可能已找到，但处于关闭状态。
* **`id_match`**：该账户的持有人是您提交的身份证件号码所对应的人。这正是本服务的核心核对项。
* **`initials_match`**、**`surname_match`**：您提交的 `initials` 和 `last_name` 与银行记录中的账户持有人一致。
* **`account_type_match`**：您提交的 `account_type` 与该账户的实际类型一致。
* **`email_match`**、**`phone_match`**：您提交的 `email` 和 `phone_number` 与银行留存的联系方式一致。
* **`accepts_debits`**、**`accepts_credits`**：该账户可以接收直接扣款指令和入账款项。
* **`account_number_length_valid`**：账号长度符合银行的规定。

结果代码对上述标志位作出总结：

* **`MATCH`**：账户存在，且您提交的每个字段都已匹配，包括 `id_match`。
* **`PARTIAL_MATCH`**：该账户的持有人是您提交的身份证件号码所对应的人，但您发送的至少一个其他字段不匹配（例如，银行记录中的姓氏拼写不同）。`outcome_detail` 会列出未通过的字段。
* **`NO_MATCH`**：银行没有该账户，或该账户属于他人。两种情况都是关于该人员的确定结论。

您未请求的交叉核对既不计入结果，也不报告。对于未提供的每个字段，AVS 都返回 `N`，因此 `surname_match`、`initials_match`、`email_match`、`phone_match` 和 `account_type_match` 只有在您发送了对应输入时才会出现在 `source_data` 中。因此，仅发送 `national_id`、`bank_account_number` 和 `bank_name` 仍会得到完整的 `MATCH`。

## 可接受的 bank\_name 与 account\_type 值

`bank_name` 和 `account_type` 是枚举值。不在列表中的值会在查询运行前被拒绝，因此输入错误只会浪费一次往返请求，而不会产生费用。

`account_type` 为可选项，不区分大小写，接受以下值：

`current` · `savings` · `transmission` · `subscriptionShare` · `notKnown`

如果您不知道账户类型，可以省略该字段。Didit 随后会发送 `notKnown`，请求成功，并且由于没有可比对的内容，`account_type_match` 返回 `false`。其他任何值（如 `checking`、`cheque`、`bond`）都会被拒绝，并返回 `400` 错误，其中列出可接受的值集合。

`bank_name` 为必填项，以下值已确认可接受（不区分大小写）：

`ABSA` · `Capitec` · `FNB` · `Nedbank` · `Standard Bank` · `Investec` · `African Bank` · `Discovery Bank` · `Old Mutual` · `Bank Zero` · `Tyme` · `Grindrod`

以上所有银行的个人账户均在服务范围内，包括 Capitec。请严格使用列出的简称，例如填写 `Capitec` 而非 `Capitec Bank`，填写 `Tyme` 而非 `TymeBank`。无法识别的银行会返回结果为 `REGISTRY_ERROR` 的响应，其 `outcome_detail` 会注明数据源拒绝的字段。

## 区分账户不存在与数据源不可用

以下情况对应不同的 HTTP 结果，因此无需解析错误字符串：

* **账户不存在**：`200 OK`，`match_type: "no_match"`，`outcome_code: "NO_MATCH"`，`source_data.account_found: false`。这是银行的真实回答。该次查询计费，并适用您的无匹配操作。
* **来源没有响应**：`502 Bad Gateway`，`validation_errors[].code` 为 `empty_provider_response`，`retryable: true`。未能确认该人员的任何信息，不计费，可以安全地重试。
* **来源拒绝执行查询**：`400 Bad Request`，`validation_errors[].code` 为 `provider_rejected_input`，`retryable: false`。数据源未执行搜索，因为它不接受所发送的内容。请更正数据，使用相同的值重试无法成功。不计费。
* **数据源已响应并拒绝了您的输入**：`502 Bad Gateway`，`validation_errors[].code` 为 `provider_invalid_input`（例如账号未通过银行自身的格式校验）。在输入更正之前重试没有意义。不计费。
* **请求从未离开 Didit**：`400 Bad Request`，并列出需要修正的字段。不计费。

只有第一种情况是关于该人员的确定答复。应将 `502` 视为临时性错误。AVS 是将请求转发给账户持有人的银行，而不是读取登记库，因此它是南非各项服务中速度最慢的。请采用退避策略进行重试。

## 继续阅读

* [南非数据库核验概述](https://docs.didit.me/api-reference/database-validation/south-africa.md)
* [数据库核验概述](https://docs.didit.me/zh/core-technology/database-validation/overview.md)
* [结果代码](https://docs.didit.me/zh/core-technology/database-validation/database-validation-outcome-codes.md)


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