> 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-verify-otp.md).

# BVN Verify OTP

Verifica el **código OTP** recibido y retorna los **datos completos del BVN** incluyendo la información personal del titular. Este es el **paso final** del flujo de verificación BVN de 3 pasos para Nigeria 🇳🇬.

### Endpoint

```
POST /kyc/nga/bvn/verify
```

### 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                                        |
| ----------- | ------ | --------- | -------------------------------------------------- |
| `sessionId` | string | **Sí**    | **ID de sesión** obtenido del paso de iniciación.  |
| `otp`       | string | **Sí**    | Código OTP recibido por el usuario. **6 dígitos.** |

#### Ejemplo de solicitud

```json
{
  "sessionId": "5f9b1a2c-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "otp": "123456"
}
```

### 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 completos del BVN. Ver tabla a continuación.                                                            |

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

El objeto `data` se retorna **sin mapeo ni normalización**, conservando los nombres, el formato y la capitalización originales de los campos.

| Parámetro           | Tipo    | Descripción                                                                                                                |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `bvn`               | string  | Bank Verification Number.                                                                                                  |
| `first_name`        | string  | Nombre(s) del titular.                                                                                                     |
| `middle_name`       | string  | Segundo nombre.                                                                                                            |
| `last_name`         | string  | Apellido(s) del titular.                                                                                                   |
| `dob`               | string  | Fecha de nacimiento (`YYYY-MM-DD`).                                                                                        |
| `phone_number`      | string  | Número de teléfono registrado.                                                                                             |
| `phone_number_2`    | string  | Número de teléfono secundario. Puede ser `null`.                                                                           |
| `email`             | string  | Dirección de correo electrónico registrada.                                                                                |
| `gender`            | string  | Género. Valores posibles: `Male`, `Female`                                                                                 |
| `state_of_origin`   | string  | Estado de origen.                                                                                                          |
| `lga_of_origin`     | string  | LGA (Local Government Area) de origen.                                                                                     |
| `lga_of_Residence`  | string  | LGA (Local Government Area) de residencia. La `R` mayúscula es literal: el campo se retorna con esa capitalización exacta. |
| `address`           | string  | Dirección registrada. Puede ser `null` o no estar presente según el registro BVN.                                          |
| `marital_status`    | string  | Estado civil.                                                                                                              |
| `nin`               | string  | National Identification Number asociado al BVN.                                                                            |
| `nationality`       | string  | Nacionalidad. Puede ser `null` o no estar presente según el registro BVN.                                                  |
| `registration_date` | string  | Fecha de registro del BVN.                                                                                                 |
| `watch_listed`      | boolean | Indica si la persona se encuentra en una **lista de vigilancia**.                                                          |
| `photoId`           | string  | Fotografía del titular codificada en **Base64**.                                                                           |

#### 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": "1500",
  "serviceResultLog": "Success",
  "serviceTransactionId": "996c790d-89d7-6c8g-c31c-7d1367ce77ef",
  "data": {
    "bvn": "12345678901",
    "first_name": "JOHN",
    "middle_name": "PAUL",
    "last_name": "DOE",
    "dob": "1990-01-15",
    "phone_number": "08012345678",
    "phone_number_2": null,
    "email": "john.doe@example.com",
    "gender": "Male",
    "state_of_origin": "Lagos State",
    "lga_of_origin": "Yaba",
    "lga_of_Residence": "Yaba",
    "address": "12 BEN STREET LAGOS",
    "marital_status": "single",
    "nin": "12345678901",
    "nationality": "Nigeria",
    "registration_date": "2015-06-20",
    "watch_listed": false,
    "photoId": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
  }
}
```

#### `400` Bad Request

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

```json
{
  "serviceResultCode": 400,
  "serviceResultLog": "Sorry, lookup failed. Please check the details and try again",
  "serviceTime": "151",
  "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 %}