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

# رقم التحقق البنكي (BVN) في نيجيريا: واجهة API

> استعلام رقم التحقق البنكي (BVN) في نيجيريا من قاعدة البيانات الرسمية عبر Didit. بالدفع لكل استدعاء بدءاً من $0.35، دون عقود أو حد أدنى.

يتحقق هذا الفحص من بيانات الإدخال مقابل قاعدة بيانات قطاع الخدمات المصرفية النيجيري. يتطلب صورة سيلفي: تُطابَق صورة التسجيل المرتبطة برقم التحقق المصرفي (BVN) مع الصورة المُدخلة، ولا يُعاد السجل إلا إذا كانت الصورتان لشخص واحد. تتيح Didit هذه الخدمة عبر `POST /v3/database-validation/` لتتمكن من التحقق من البيانات المُرسلة مقابل المصدر الموثوق، والحصول على نتائج مطابقة موحدة. صيغة الإدخال: يقبل الحقل `bvn` رقم التحقق المصرفي النيجيري (11 رقمًا بالضبط).

## التغطية

* **التغطية:** \~ 100%
* **الدولة:** نيجيريا
* **معرّف الخدمة:** `nga_bank_verification_number`
* **نطاق البيانات:** مالي
* **الفئة:** الخدمات المصرفية

## المدخلات

| الحقل | مطلوب | مثال |
| - | -: | - |
| `bvn` | نعم | `11111111111` |
| `selfie` | نعم | `@./selfie.jpg` |
| `first_name` | لا | `John` |
| `last_name` | لا | `Doe` |
| `date_of_birth` | لا | `1990-01-01` |
| `vendor_data` | لا | `user-1234` |

* **المدخلات المطلوبة:** `bvn`، `selfie`
* **المدخلات الاختيارية:** `first_name`، `last_name`، `date_of_birth`، `vendor_data`
* **الموافقة:** غير مطلوبة
* **توفر الخدمة في سير العمل:** متاحة في سير العمل مع ربط الحقول
* **التغطية:** \~ 100%
* **السعر:** \$0.35 لكل استعلام ناجح

في سير العمل، لا يُطبع الرقم `bvn` على أي وثيقة هوية، لذلك لا تنتجه أي خطوة بمفردها. اجمعه من إجابة في الاستبيانات، أو من حقل مستخرج عبر Document AI، أو من قيمة ترسلها عند إنشاء الجلسة، ثم اربطه في خطوة التحقق من قواعد البيانات. إلى أن يُربط هذا الحقل، يعرض محرر سير العمل هذه الخدمة معطّلة ويذكر المدخل الناقص. وعند التشغيل، يعني المدخل الناقص أن الفحص يُتخطى قبل أي استعلام، فلا تُحتسب عليك تكلفة لقاعدة بيانات لم يكن بالإمكان الاستعلام عنها.

## معاملات الجسم

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

رمز الدولة وفق ISO 3166-1 alpha-3 لخدمة قاعدة البيانات هذه.

مثال: `NGA`

**services** `string` *required* (default: nga\_bank\_verification\_number)

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

مثال: `nga_bank_verification_number`

**bvn** `string` *required* (default: 11111111111)

رقم التحقق المصرفي.

مثال: `11111111111`

**selfie** `file` *required*

ملف صورة السيلفي المراد رفعه للتحقق البيومتري من قاعدة البيانات. الصيغ المقبولة: JPEG أو PNG أو WebP.

مثال: `@./selfie.jpg`

**first\_name** `string`

الاسم الأول المراد التحقق منه.

مثال: `John`

**last\_name** `string`

اسم العائلة المراد التحقق منه.

مثال: `Doe`

**date\_of\_birth** `string` (default: 1990-01-01)

تاريخ الميلاد بصيغة `YYYY-MM-DD`.

مثال: `1990-01-01`

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

المرجع الثابت للمستخدم لدى نظامك، مثل معرّف المستخدم الداخلي. تستخدمه Didit لربط الفحوصات المستقلة بالمستخدم النهائي نفسه، وتقليل التشويش في كشف التكرار.

مثال: `user-1234`

## قواعد المدخلات وملاحظات التحقق

* رقم التحقق المصرفي النيجيري (11 رقمًا بالضبط)
* يجب أن يحتوي `bvn` على أرقام فقط؛ أزل المسافات والشرطات وعلامات الترقيم قبل إرسال الطلب.
* يجب أن يكون طول `bvn` 11 حرفًا بالضبط.

## كيفية الاستدعاء

```bash cURL theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=NGA" \
  -F "services=nga_bank_verification_number" \
  -F "vendor_data=user-1234" \
  -F "bvn=11111111111" \
  -F "selfie=@./selfie.jpg" \
  -F "date_of_birth=1990-01-01"
```

```python Python theme={null}
from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.database_validation.validate(
    issuing_state="NGA",
    services=["nga_bank_verification_number"],
    date_of_birth="1990-01-01",
    bvn="11111111111",
    vendor_data="user-1234",
    selfie=open("selfie.jpg", "rb"),
)
print(result)
```

```javascript Node.js theme={null}
import Didit, { fileFromPath } from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.databaseValidation.validate({
  issuing_state: "NGA",
  services: ["nga_bank_verification_number"],
  date_of_birth: "1990-01-01",
  bvn: "11111111111",
  vendor_data: "user-1234",
  selfie: await fileFromPath("selfie.jpg"),
});
console.log(result);
```

```go Go theme={null}
ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{
	IssuingState: "NGA",
	Services:     didit.Some([]string{"nga_bank_verification_number"}),
	DateOfBirth:  didit.String("1990-01-01"),
	Bvn:          didit.String("11111111111"),
	VendorData:   didit.String("user-1234"),
	Selfie:       didit.Some(didit.FileFromPath("selfie.jpg")),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)
```

```java Java theme={null}
import java.nio.file.Path;
import java.time.LocalDate;
import java.util.List;
import me.didit.Didit;
import me.didit.types.DatabaseValidationValidateParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder()
        .issuingState("NGA")
        .services(List.of("nga_bank_verification_number"))
        .dateOfBirth(LocalDate.parse("1990-01-01"))
        .bvn("11111111111")
        .vendorData("user-1234")
        .selfie(Path.of("selfie.jpg"))
        .build());
System.out.println(result);
```

```php PHP theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\File;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->databaseValidation->validate([
    'issuing_state' => 'NGA',
    'services' => ['nga_bank_verification_number'],
    'date_of_birth' => '1990-01-01',
    'bvn' => '11111111111',
    'vendor_data' => 'user-1234',
    'selfie' => File::fromPath('selfie.jpg'),
]);
print_r($result->toArray());
```

```ruby Ruby theme={null}
require "didit"

# Reads DIDIT_API_KEY.
didit = Didit::Client.new

result = didit.database_validation.validate(
  issuing_state: "NGA",
  services: ["nga_bank_verification_number"],
  date_of_birth: "1990-01-01",
  bvn: "11111111111",
  vendor_data: "user-1234",
  selfie: Pathname("selfie.jpg")
)
puts result.to_h
```

```csharp .NET theme={null}
using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams
{
    IssuingState = "NGA",
    Services = new string[] { "nga_bank_verification_number" },
    DateOfBirth = "1990-01-01",
    Bvn = "11111111111",
    VendorData = "user-1234",
    Selfie = FileUpload.FromPath("selfie.jpg"),
});
Console.WriteLine(JsonSerializer.Serialize(result));
```

تُعيد كل استدعاء ناجح الرمز HTTP `200`. يوضح الحقل **`outcome_code`** ما حدث فعليًا، فيميّز مثلًا بين عدم تطابق بيومتري حقيقي (`BIOMETRIC_NO_MATCH`) وبين سيلفي تعذّرت قراءته (`BIOMETRIC_IMAGE_UNUSABLE`). الحالة `status` المعروضة هي الحالة الافتراضية للميزة، ويمكن لـ[إجراءات التطابق الجزئي وعدم التطابق](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": "NGA",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "nga_bank_verification_number",
      "service_name": "Nigeria Bank Verification Number (BVN)",
      "source_data": {
        "date_of_birth": "1990-01-01",
        "first_name": "John",
        "last_name": "Doe"
      },
      "validation": {
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`PARTIAL_MATCH`**: رقم التحقق المصرفي موجود في السجلات، وتطابقت صورة السيلفي مع صورة التسجيل لدى NIBSS، لكن اسمًا أو تاريخ ميلاد أرسلته لا يتفق مع السجل. يُعاد السجل حتى تتمكن من رؤية الحقل المختلف.

```json 200 OK — PARTIAL_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "NGA",
  "match_type": "partial_match",
  "validations": [
    {
      "outcome_code": "PARTIAL_MATCH",
      "service_id": "nga_bank_verification_number",
      "service_name": "Nigeria Bank Verification Number (BVN)",
      "source_data": {
        "date_of_birth": "1990-01-01",
        "first_name": "John",
        "last_name": "Doe"
      },
      "validation": {
        "date_of_birth": "no_match",
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`BIOMETRIC_NO_MATCH`**: كانت درجة مطابقة الوجه أقل من حد القبول، أي أن السيلفي ليست للشخص نفسه الموجود في صورة السجل.

```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "NGA",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "BIOMETRIC_NO_MATCH",
      "service_id": "nga_bank_verification_number",
      "service_name": "Nigeria Bank Verification Number (BVN)",
      "source_data": {
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "identification_number": "no_match"
      }
    }
  ]
}
```

**`INCONCLUSIVE`**: لم تتمكن السجلات من تحديد ما إذا كان الشخص مطابقًا، فالنتيجة غير محسومة فعلًا (قد يكون الشخص مسجلًا أو لا يكون). هذه النتيجة ليست حالة عدم تطابق، وليست مشكلة تقنية في الصورة؛ لا يُؤكَّد أي حقل، ولذلك يكون match\_type قيمته null، ويُحال الفحص إلى المراجعة اليدوية.

```json 200 OK — INCONCLUSIVE theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "NGA",
  "match_type": null,
  "validations": [
    {
      "outcome_code": "INCONCLUSIVE",
      "service_id": "nga_bank_verification_number",
      "service_name": "Nigeria Bank Verification Number (BVN)",
      "source_data": {},
      "validation": {}
    }
  ]
}
```

**`DOCUMENT_NOT_FOUND`**: رقم الوثيقة المُرسل لا يطابق أي سجل في السجلات.

```json 200 OK — DOCUMENT_NOT_FOUND theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "NGA",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "DOCUMENT_NOT_FOUND",
      "service_id": "nga_bank_verification_number",
      "service_name": "Nigeria Bank Verification Number (BVN)",
      "source_data": {
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "identification_number": "no_match"
      }
    }
  ]
}
```

## البيانات المُعادة

تعتمد الحقول الدقيقة المعروضة في `source_data` على ما تعيده السجلات. يوثّق المثال المُولَّد للخدمة `nga_bank_verification_number` حاليًا هذا الشكل الموحد:

* `date_of_birth`
* `first_name`
* `last_name`

## الأسعار واتفاقيات مستوى الخدمة

تُحتسب استعلامات رقم التحقق المصرفي النيجيري (BVN) فقط عندما تتلقى Didit نتيجة حاسمة من مصدر التحقق.

* **سعر الاستدعاء الواحد:** \$0.35 USD.
* **الفوترة:** لكل استعلام ناجح. لا تُحتسب عليك تكلفة عندما يتعذر الوصول إلى السجل، أو عندما تكون الحقول المطلوبة ناقصة، أو عندما يُرفض الطلب قبل أن يصل إلى المصدر.
* **زمن الاستجابة:** p95 نموذجيًا \< 2 s.
* **التوفر:** 99.9% لكل ربع سنة من جهة Didit؛ ويختلف توفر المصدر النهائي حسب الدولة ومجموعة البيانات.

## متابعة القراءة

* [نظرة عامة على التحقق من قواعد البيانات في نيجيريا](https://docs.didit.me/api-reference/database-validation/nigeria.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.