> ## 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.

# Verificació del titular del compte bancari a Sud-àfrica

> Verifica el titular del compte bancari a Sud-àfrica amb Didit: consulta oficial en bases de dades des de $0.40 per crida. Sense contractes.

Confirma que un compte bancari de Sud-àfrica pertany al titular indicat mitjançant el servei interbancari de verificació del titular del compte. Didit exposa aquest servei a través de `POST /v3/database-validation/` perquè puguis verificar les dades enviades contra la font autoritativa i rebre resultats de coincidència normalitzats.

## Cobertura

* **Cobertura:** —
* **País:** Sud-àfrica
* **ID del servei:** `zaf_bank_account_holder`
* **Domini de dades:** Financera
* **Categoria:** Banca

## Entrades

| Camp | Obligatori | Exemple |
| - | -: | - |
| `national_id` | Sí | `8708150847085` |
| `bank_account_number` | Sí | `1234567890` |
| `bank_name` | Sí | `ABSA` |
| `account_type` | No | `current` |
| `first_name` | No | `John` |
| `last_name` | No | `Doe` |
| `initials` | No | `JD` |
| `email` | No | `john.doe@example.com` |
| `phone_number` | No | `+15550101000` |
| `vendor_data` | No | `user-1234` |

* **Entrades obligatòries:** `national_id`, `bank_account_number`, `bank_name`
* **Entrades opcionals:** `account_type`, `first_name`, `last_name`, `initials`, `email`, `phone_number`, `vendor_data`
* **Consentiment:** Obligatori
* **Disponibilitat al flux de treball:** Disponible en un flux de treball amb mapatge de camps
* **Cobertura:** —
* **Preu:** \$0.40 per consulta satisfactòria

En un flux de treball, `bank_account_number` i `bank_name` no apareixen impresos en cap document d'identitat, de manera que cap pas no els produeix per si sol. Recull-los d'una resposta de Qüestionari, d'un camp d'extracció de Document AI o d'un valor que envies en crear la sessió, i mapa cadascun en el pas de Validació en bases de dades. Mentre no estiguin mapats, l'editor del flux de treball mostra aquest servei desactivat i indica quina entrada falta. En execució, una entrada que falta fa que la comprovació s'omet abans de cap consulta, de manera que mai no et cobren per una base de dades a la qual no s'ha pogut fer cap consulta.

## Paràmetres del cos

**issuing\_state** `string` *required* (default: ZAF)

Codi de país ISO 3166-1 alpha-3 per a aquest servei de base de dades.

Exemple: `ZAF`

**services** `string` *required* (default: zaf\_bank\_account\_holder)

Matriu que conté l'ID d'aquest servei. Fixar el servei manté la sol·licitud limitada a aquesta base de dades exacta.

Exemple: `zaf_bank_account_holder`

**consent** `boolean` *required* (default: true)

Consentiment explícit de l'usuari final per a aquest servei.

Exemple: `true`

**national\_id** `string` *required* (default: 8708150847085)

Número d'identitat nacional per a aquest servei.

Exemple: `8708150847085`

**bank\_account\_number** `string` *required* (default: 1234567890)

Valor de `bank_account_number` que requereix aquest servei de base de dades.

Exemple: `1234567890`

**bank\_name** `string` *required* (default: ABSA)

Valor de `bank_name` que requereix aquest servei de base de dades.

Exemple: `ABSA`

**account\_type** `string` (default: current)

Valor de `account_type` que requereix aquest servei de base de dades.

Exemple: `current`

**first\_name** `string`

Nom de pila a validar.

Exemple: `John`

**last\_name** `string` (default: Doe)

Cognoms a validar.

Exemple: `Doe`

**initials** `string` (default: JD)

Valor de `initials` que requereix aquest servei de base de dades.

Exemple: `JD`

**email** `string`

Adreça de correu electrònic.

Exemple: `john.doe@example.com`

**phone\_number** `string`

Valor de `phone_number` que requereix aquest servei de base de dades.

Exemple: `+15550101000`

**vendor\_data** `string` (default: user-1234)

La teva referència d'usuari estable per a aquesta persona, com ara el teu ID d'usuari intern. Didit l'utilitza per vincular les comprovacions independents amb el mateix usuari final i reduir el soroll de la detecció de duplicats.

Exemple: `user-1234`

## Regles d'entrada i notes de validació

* `account_type` ha de ser un dels tipus de compte AVS de Sud-àfrica: `current`, `savings`, `transmission`, `subscriptionShare`, `notKnown`. La comparació no distingeix entre majúscules i minúscules. Omet el camp si no saps el tipus de compte: Didit aleshores envia `notKnown` i la verificació creuada del tipus de compte s'informa com a no confirmada, en lloc de fer fallar la sol·licitud.

## Com fer la crida

```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"
```

Cada crida satisfactòria retorna HTTP `200`. El camp **`outcome_code`** t'indica què ha passat realment, i distingeix, per exemple, una discrepància biomètrica real (`BIOMETRIC_NO_MATCH`) d'una selfie que no s'ha pogut llegir (`BIOMETRIC_IMAGE_UNUSABLE`). L'`status` que es mostra és l'estat per defecte de la funcionalitat; les teves [accions de coincidència parcial / sense coincidència](https://docs.didit.me/ca/core-technology/database-validation/database-validation-warnings.md) configurades el poden substituir.

**`MATCH`**: El registre ha confirmat la identitat i tots els camps verificats han coincidit.

```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`**: S'ha trobat el número d'identificació, però un o més camps personals (normalment el nom o la data de naixement) no han coincidit completament.

```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`**: El registre no ha retornat cap coincidència per a les dades enviades.

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

## Dades retornades

Els camps exactes que es mostren a `source_data` depenen del que retorni el registre. L'exemple generat per a `zaf_bank_account_holder` documenta actualment aquesta estructura normalitzada:

* `accepts_credits`
* `accepts_debits`
* `account_found`
* `account_number_length_valid`
* `account_open`
* `account_type_match`
* `id_match`
* `identification_number`
* `initials_match`
* `surname_match`

## Preus i SLA

Les consultes de verificació del titular del compte bancari de Sud-àfrica es facturen només quan Didit rep un resultat concloent de la font de validació.

* **Preu per crida:** \$0.40 USD.
* **Facturació:** per consulta satisfactòria. No se't cobrarà quan el registre sigui inaccessible, quan falti algun camp obligatori o quan la sol·licitud es rebutgi abans d'arribar a la font.
* **Latència:** p95 típic \< 2 s.
* **Disponibilitat:** 99.9% per trimestre per part de Didit; la disponibilitat de la font externa varia segons el país i el conjunt de dades.

## Què confirma una COINCIDÈNCIA

La verificació del titular del compte (AVS) és un conjunt de comprovacions creuades de sí o no, no una consulta de registre. La font mai retorna un nom, un número d'identitat ni un saldo de compte. Compara les dades que li envies amb el que el banc té registrat per a aquell compte i respon cada comparació amb un indicador. `source_data` conté aquests indicadors:

* **`account_found`**: el banc té un compte amb aquest número. Tota la resta no té sentit quan és `false`.
* **`account_open`**: el compte està obert. Un compte pot existir però estar tancat.
* **`id_match`**: el compte està associat a l'identificador nacional que has enviat. Aquesta és la comprovació per a la qual existeix el servei.
* **`initials_match`**, **`surname_match`**: les `initials` i el `last_name` enviats coincideixen amb el titular registrat.
* **`account_type_match`**: el `account_type` enviat coincideix amb el tipus real del compte.
* **`email_match`**, **`phone_match`**: el `email` i el `phone_number` enviats coincideixen amb les dades de contacte que té el banc.
* **`accepts_debits`**, **`accepts_credits`**: el compte pot rebre ordres de dèbit i abonaments.
* **`account_number_length_valid`**: el número de compte té la longitud que espera el banc.

El codi de resultat resumeix aquests indicadors:

* **`MATCH`**: el compte existeix i tots els camps que has enviat coincideixen, inclòs `id_match`.
* **`PARTIAL_MATCH`**: el compte està associat a l'identificador nacional enviat, però com a mínim un altre camp que has enviat no coincideix (per exemple, un cognom escrit de manera diferent als registres del banc). `outcome_detail` indica els camps que han fallat.
* **`NO_MATCH`**: o bé el banc no té cap compte amb aquest número, o bé el compte existeix però pertany a una altra persona. Les dues són respostes concloents sobre la persona.

Una comprovació creuada que no has demanat no es compta ni es retorna. AVS respon `N` a cada camp que no s'ha proporcionat, de manera que `surname_match`, `initials_match`, `email_match`, `phone_match` i `account_type_match` només apareixen a `source_data` quan has enviat la dada corresponent. Per tant, enviar només `national_id`, `bank_account_number` i `bank_name` continua produint una `MATCH` completa.

## Valors acceptats de bank\_name i account\_type

`bank_name` i `account_type` són enumeracions. Un valor que no formi part de cap de les dues llistes es rebutja abans d'executar la consulta, de manera que un error tipogràfic costa un viatge d'anada i tornada i no un cobrament.

`account_type` és opcional i accepta, sense distingir majúscules de minúscules:

`current` · `savings` · `transmission` · `subscriptionShare` · `notKnown`

Omet-lo quan no coneguis el tipus de compte. Didit envia aleshores `notKnown`, la sol·licitud té èxit i `account_type_match` retorna `false` perquè no hi havia res a comparar. Qualsevol altre valor (`checking`, `cheque`, `bond`) es rebutja amb un `400` que indica el conjunt acceptat.

`bank_name` és obligatori i aquests valors estan confirmats com a acceptats (sense distingir majúscules de minúscules):

`ABSA` · `Capitec` · `FNB` · `Nedbank` · `Standard Bank` · `Investec` · `African Bank` · `Discovery Bank` · `Old Mutual` · `Bank Zero` · `Tyme` · `Grindrod`

Els comptes de particulars de tots aquests bancs estan inclosos, també el de Capitec. Envia la forma curta exactament tal com figura a la llista: `Capitec`, no `Capitec Bank`; `Tyme`, no `TymeBank`. Un banc no reconegut retorna un resultat `REGISTRY_ERROR` amb un `outcome_detail` que indica el camp que la font ha rebutjat.

## Distingir un compte inexistent d'una font no disponible

Aquests són resultats HTTP diferents, de manera que no cal analitzar cap text d'error:

* **El compte no existeix**: `200 OK`, `match_type: "no_match"`, `outcome_code: "NO_MATCH"`, `source_data.account_found: false`. És una resposta real del banc. Es factura i s'aplica la teva acció per a les no coincidències.
* **La font no va respondre**: `502 Bad Gateway` amb `validation_errors[].code` = `empty_provider_response` i `retryable: true`. No s'ha establert res sobre la persona, no es factura res i la sol·licitud es pot reintentar sense risc.
* **La font es va negar a executar la consulta**: `400 Bad Request` amb `validation_errors[].code` = `provider_rejected_input` i `retryable: false`. La font mai no va fer la cerca, perquè no acceptava el que se li havia enviat. Corregeix les dades; reintentar els mateixos valors no pot tenir èxit. No es factura res.
* **La font va respondre i va rebutjar la teva entrada**: `502 Bad Gateway` amb `validation_errors[].code` = `provider_invalid_input` (per exemple, un número de compte que no supera la validació de format del propi banc). Reintentar no té sentit fins que no es corregeixi l'entrada; no es factura res.
* **La sol·licitud no va sortir de Didit**: `400 Bad Request`, que indica el camp a corregir. No es factura res.

Només el primer d'aquests resultats és una resposta sobre la persona. Considera un `502` com a transitori: AVS consulta el banc del titular del compte en lloc de llegir un registre, de manera que és el més lent dels serveis de Sud-àfrica. Reintenta amb backoff.

## Continua llegint

* [Visió general de la validació de bases de dades de Sud-àfrica](https://docs.didit.me/api-reference/database-validation/south-africa.md)
* [Visió general de la validació de bases de dades](https://docs.didit.me/ca/core-technology/database-validation/overview.md)
* [Codis de resultat](https://docs.didit.me/ca/core-technology/database-validation/database-validation-outcome-codes.md)


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