> ## 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/`, чтобы вы могли сверить переданные данные с достоверным источником и получить нормализованные результаты сопоставления.

## Покрытие

* **Покрытие:** —
* **Страна:** Южная Африка
* **Идентификатор сервиса:** `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/ru/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 с.
* **Доступность:** 99.9% в квартал со стороны Didit; доступность источников данных зависит от страны и набора данных.

## Что подтверждает 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/ru/core-technology/database-validation/overview.md)
* [Коды результатов](https://docs.didit.me/ru/core-technology/database-validation/database-validation-outcome-codes.md)


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