> ## 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から、契約不要、最低利用額なし。

銀行間のAccount Holder Verificationサービスを通じて、南アフリカの銀行口座が指定された名義人のものであることを確認します。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`
* **同意：** 必須
* **ワークフローでの利用：** フィールドマッピングを設定すればワークフローで利用可能
* **対象範囲：** -
* **料金：** 成功したクエリ1件あたり\$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/ja/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`**：識別番号は見つかりましたが、1つ以上の個人情報フィールド(通常は氏名または生年月日)が完全には一致しませんでした。

```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が検証情報源から確定した結果を受け取った場合にのみ課金されます。

* **1回の呼び出しあたりの料金:** \$0.40 USD。
* **請求:** 成功したクエリごとに課金されます。レジストリに到達できない場合、必須フィールドが欠落している場合、またはリクエストが情報源に届く前に拒否された場合は課金されません。
* **レイテンシー:** p95で通常2秒未満。
* **可用性:** Didit側で四半期あたり99.9%。下流の情報源の可用性は国やデータセットによって異なります。

## MATCHが確認する内容

口座名義人検証(AVS)は、記録を検索するものではなく、「はい」か「いいえ」で答える一連の照合チェックです。情報源が氏名、ID番号、口座残高を返すことはありません。送信された情報を、その口座について銀行が保持している情報と比較し、各比較の結果をフラグで返します。`source_data`にはこれらのフラグが含まれます。

* **`account_found`**: 銀行にこの番号の口座があります。これが`false`の場合、他のフラグはすべて意味を持ちません。
* **`account_open`**: 口座が開設されています。口座が見つかっても解約済みの場合があります。
* **`id_match`**: 送信した国民IDが口座名義人の国民IDと一致しています。このサービスの目的となるチェックです。
* **`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`**: 送信した国民IDは口座名義人の国民IDと一致していますが、送信した他のフィールドのうち少なくとも1つが一致しませんでした(例: 銀行の記録上で姓の綴りが異なる場合)。`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`は列挙型です。どちらかのリストにない値はクエリの実行前に拒否されるため、入力ミスがあっても課金は発生せず、リクエストの往復が1回増えるだけで済みます。

`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 Bank`ではなく`Capitec`、`TymeBank`ではなく`Tyme`です。認識されない銀行の場合、`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/ja/core-technology/database-validation/overview.md)
* [結果コード](https://docs.didit.me/ja/core-technology/database-validation/database-validation-outcome-codes.md)


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