> ## 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`
* **동의:** 필수
* **워크플로 사용 가능 여부:** 필드 매핑을 통해 워크플로에서 사용 가능
* **적용 범위:** —
* **요금:** 성공한 쿼리당 \$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/ko/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 s.
* **가용성:** 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 Bank`가 아니라 `Capitec`, `TymeBank`가 아니라 `Tyme`입니다. 인식되지 않는 은행은 `outcome_detail`에 검증 기관이 거부한 필드가 명시된 `REGISTRY_ERROR` 결과로 반환됩니다.

## 계좌 부재와 출처 불가용 상태 구분하기

이들은 서로 다른 HTTP 응답이므로 오류 문자열을 파싱할 필요가 없습니다:

* **계좌가 존재하지 않음** - `200 OK`, `match_type: "no_match"`, `outcome_code: "NO_MATCH"`, `source_data.account_found: false`. 은행으로부터 받은 실제 응답입니다. 과금되며, 설정한 no-match 작업이 적용됩니다.
* **검증 기관이 응답하지 않았습니다** - `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/ko/core-technology/database-validation/overview.md)
* [결과 코드](https://docs.didit.me/ko/core-technology/database-validation/database-validation-outcome-codes.md)


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