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

مصفوفة تحتوي على معرّف هذه الخدمة. تثبيت الخدمة يُبقي الطلب مقتصراً على قاعدة البيانات المحددة هذه.

مثال: `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)

معرّفك الثابت لهذا الشخص، مثل معرّف المستخدم الداخلي لديك. تستخدمه 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` المعروضة حالة الميزة الافتراضية، ويمكن لـ[إجراءات Partial Match / No Match](https://docs.didit.me/ar/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)

لا تُحتسب استعلامات South Africa - Bank Account Holder Verification إلا عندما تستلم Didit نتيجة قاطعة من مصدر التحقق.

* **السعر لكل استدعاء:** \$0.40 USD.
* **الفوترة:** لكل استعلام ناجح. لا يُحتسب أي مبلغ عند تعذر الوصول إلى السجل، أو عند غياب الحقول المطلوبة، أو عند رفض الطلب قبل وصوله إلى المصدر.
* **زمن الاستجابة:** p95 النموذجي أقل من ثانيتين.
* **التوفر:** 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/ar/core-technology/database-validation/overview.md)
* [رموز النتائج](https://docs.didit.me/ar/core-technology/database-validation/database-validation-outcome-codes.md)


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