南アフリカ銀行口座名義人確認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"
      }
    }
  ]
}

銀行間の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の抽出フィールド、またはセッション作成時に送信する値から取得し、それぞれをデータベース検証ステップでマッピングしてください。マッピングが完了するまで、ワークフローエディターではこのサービスが無効と表示され、不足している入力の名前が示されます。実行時に入力が不足している場合はクエリの前にチェックがスキップされるため、照会できなかったデータベースについて請求されることはありません。

ボディパラメーター

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：識別番号は見つかりましたが、1つ以上の個人情報フィールド(通常は氏名または生年月日)が完全には一致しませんでした。

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

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はレジストリを参照するのではなく、口座名義人の銀行にリクエストを中継するため、南アフリカのサービスの中で最も応答が遅くなります。

​対象範囲

​入力

​ボディパラメーター

​入力ルールと検証に関する注意事項

​呼び出し方法

​返却されるデータ

​料金とSLA

​MATCHが確認する内容

​使用できるbank_nameとaccount_typeの値

​存在しない口座と利用できない情報源の見分け方

​関連情報

対象範囲

入力

ボディパラメーター

入力ルールと検証に関する注意事項

呼び出し方法

返却されるデータ

料金とSLA

MATCHが確認する内容

使用できるbank_nameとaccount_typeの値

存在しない口座と利用できない情報源の見分け方

関連情報