> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/api-rest/identity-api/identity-api-reference/onboarding/kyc/nigeria/bvn-verification/bvn-initiate.md).

# BVN Initiate

Inicia el proceso de verificación **BVN** (Bank Verification Number) para Nigeria y retorna los **métodos de verificación disponibles** (`phone`, `phone_1`, `email`, `alternate_phone`) para el envío de OTP.

### Endpoint

```
POST /kyc/nga/bvn/initiate
```

### Autenticación

| Tipo    | Ubicación | Nombre        |
| ------- | --------- | ------------- |
| API Key | Header    | **x-api-key** |

### Cuerpo de la solicitud

**Content-Type:** `application/json`

#### Parámetros

| Parámetro | Tipo   | Requerido | Descripción                                                           |
| --------- | ------ | --------- | --------------------------------------------------------------------- |
| `bvn`     | string | **Sí**    | Bank Verification Number de **11 dígitos**.                           |
| `scope`   | string | **Sí**    | Alcance de la consulta. Valores posibles: `identity`, `bank_accounts` |

#### Ejemplo de solicitud

```json
{
  "bvn": "12345678901",
  "scope": "identity"
}
```

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro              | Tipo    | Descripción                                                                                                                  |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`    | integer | Código que indica el **resultado general** de la ejecución del servicio. Ver [Service Result Code](#service-result-code)     |
| `serviceTime`          | string  | Tiempo de procesamiento **(milisegundos)**.                                                                                  |
| `serviceResultLog`     | string  | Campo descriptivo del resultado de la ejecución del servicio. Incluye detalles cuando hay un error o excepción en el módulo. |
| `serviceTransactionId` | string  | Identificador de transacción asociado a la solicitud procesada por la API.                                                   |
| `data`                 | object  | Objeto con los datos de la sesión y métodos disponibles. Ver tabla a continuación.                                           |

#### Parámetros de respuesta — `data`

| Parámetro    | Tipo   | Descripción                                                             |
| ------------ | ------ | ----------------------------------------------------------------------- |
| `session_id` | string | **ID de sesión** para los siguientes pasos de verificación.             |
| `methods`    | array  | Métodos disponibles para la verificación OTP. Ver tabla a continuación. |

#### Parámetros de respuesta — `data.methods[]`

| Parámetro | Tipo   | Descripción                                                                                                                                                  |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `method`  | string | Tipo de método de verificación. Valores posibles: `phone`, `phone_1`, `email`, `alternate_phone`                                                             |
| `hint`    | string | Frase completa que indica dónde se enviará el código, e incluye el teléfono o correo electrónico **parcialmente enmascarado**. El texto exacto puede variar. |

#### Service Result Code

El `serviceResultCode` indica el resultado general de la ejecución del servicio:

| serviceResultCode | Descripción                                                                          | Código HTTP |
| ----------------- | ------------------------------------------------------------------------------------ | ----------- |
| 200               | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200         |

#### Ejemplo de respuesta

```json
{
  "serviceResultCode": 200,
  "serviceTime": "1200",
  "serviceResultLog": "Success",
  "serviceTransactionId": "796a580b-67b5-4a6e-a19a-5b9145ad55cd",
  "data": {
    "session_id": "5f9b1a2c-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
    "methods": [
      {
        "method": "phone",
        "hint": "Sms with a verification code will be sent to phone 0803***3843"
      },
      {
        "method": "email",
        "hint": "An email with a verification code will be sent to j***doe@example.com"
      },
      {
        "method": "alternate_phone",
        "hint": "Sms with a verification code will be sent to your alternate phone number"
      }
    ]
  }
}
```

#### `400` Bad Request

Error retornado con el sobre del servicio (`serviceResultCode` refleja el código HTTP de la respuesta):

```json
{
  "serviceResultCode": 400,
  "serviceResultLog": "Invalid BVN format. Please check the details and try again",
  "serviceTime": "120",
  "serviceTransactionId": "08ac9699-dc9e-4cdc-81d7-264f71838309"
}
```

#### `502` Bad Gateway

Se retorna cuando el servicio no está disponible temporalmente o su respuesta no pudo interpretarse. El cuerpo usa el sobre del servicio con `serviceResultCode: 500`:

```json
{
  "serviceResultCode": 500,
  "serviceResultLog": "Service temporarily unavailable. Please try again later",
  "serviceTime": "3000",
  "serviceTransactionId": "38de2932-0f2h-7gff-14g0-597h04161632"
}
```

#### `504` Gateway Timeout

Error de **timeout**, retornado con el sobre del servicio:

```json
{
  "serviceResultCode": 504,
  "serviceResultLog": "Request timeout. Please try again",
  "serviceTime": "30000",
  "serviceTransactionId": "48ef3043-1g3i-8hgg-25h1-608i15272743"
}
```

{% hint style="info" %}
Los errores de autenticación (`401`/`403`) son rechazados por el **gateway antes de llegar al servicio** y **no** usan el sobre `serviceResultCode`. Los errores de validación de la plataforma usan el formato `application/problem+json`. Consulta [Manejo de errores](/api-rest/identity-api/identity-api-reference/onboarding/kyc/nigeria.md#manejo-de-errores) para el detalle de las tres formas de respuesta.
{% endhint %}