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

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"

{
  "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"
      }
    }
  ]
}

{
  "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"
      }
    }
  ]
}

{
  "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"
      }
    }
  ]
}

POST

database-validation

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"

{
  "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"
      }
    }
  ]
}

{
  "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"
      }
    }
  ]
}

{
  "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"
      }
    }
  ]
}

确认南非银行账户归指定持有人所有，依据是银行间账户持有人核验服务。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 提取字段，或您在创建会话时发送的值中收集这些数据，并在数据库核验步骤中分别映射。在完成映射之前，工作流编辑器会将此服务显示为禁用，并指出缺少的输入；运行时如果缺少输入，该检查会在任何查询之前跳过，因此您永远不会为无法查询的数据库付费。

请求体参数

string

默认值:"ZAF"

必填

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

string

默认值:"zaf_bank_account_holder"

必填

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

终端用户对此服务的明确同意。示例：true

string

默认值:"8708150847085"

必填

此服务的国民身份号码。示例：8708150847085

string

默认值:"1234567890"

必填

此数据库服务所需的 bank_account_number 值。示例：1234567890

string

默认值:"ABSA"

必填

此数据库服务所需的 bank_name 值。示例：ABSA

string

默认值:"current"

此数据库服务所需的 account_type 值。示例：current

string

需要核验的名字。示例：John

string

默认值:"Doe"

需要核验的姓氏。示例：Doe

string

默认值:"JD"

此数据库服务所需的 initials 值。示例：JD

string

电子邮箱地址。示例：john.doe@example.com

string

此数据库服务所需的 phone_number 值。示例：+15550101000

string

默认值:"user-1234"

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

输入规则与验证说明

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

调用方法

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 是默认功能状态；您配置的部分匹配 / 不匹配操作可以覆盖它。

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

{
  "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：找到了证件号码，但一个或多个个人字段（通常是姓名或出生日期）未完全匹配。

{
  "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：注册表未返回与所提交数据匹配的结果。

{
  "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 是将请求转发给账户持有人的银行，而不是读取登记库，因此它是南非各项服务中速度最慢的。请采用退避策略进行重试。

继续阅读

最后修改于 2026年11月7日

​覆盖范围

​输入

​请求体参数

​输入规则与验证说明

​调用方法

​返回数据

​定价与 SLA

​MATCH 代表什么

​可接受的 bank_name 与 account_type 值

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

​继续阅读

覆盖范围

输入

请求体参数

输入规则与验证说明

调用方法

返回数据

定价与 SLA

MATCH 代表什么

可接受的 bank_name 与 account_type 值

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

继续阅读