Iniciar BVN

Inicia o processo de verificação BVN (Bank Verification Number) para a Nigéria e retorna os métodos de verificação disponíveis (phone, phone_1, email, alternate_phone) para o envio de OTP.

Endpoint

POST /kyc/nga/bvn/initiate

Autenticação

Tipo	Localização	Nome
API Key	Cabeçalho	x-api-key

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
bvn	string	Sim	Número de Verificação Bancária de 11 dígitos.
scope	string	Sim	Escopo da consulta. Valores possíveis: identity, bank_accounts

Exemplo de solicitação

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

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro	Tipo	Descrição
serviceResultCode	integer	Código que indica o resultado geral da execução do serviço. Ver Código de Resultado do Serviço
serviceTime	string	Tempo de processamento (milissegundos).
serviceResultLog	string	Campo descritivo do resultado da execução do serviço. Inclui detalhes quando há um erro ou exceção no módulo.
serviceTransactionId	string	Identificador de transação associado à solicitação processada pela API.
data	object	Objeto com os dados da sessão e métodos disponíveis. Veja a tabela abaixo.

Parâmetros de resposta — data

Parâmetro	Tipo	Descrição
session_id	string	ID da sessão para as próximas etapas de verificação.
methods	array	Métodos disponíveis para a verificação OTP. Veja a tabela abaixo.

Parâmetros de resposta — data.methods[]

Parâmetro	Tipo	Descrição
method	string	Tipo de método de verificação. Valores possíveis: phone, phone_1, email, alternate_phone
hint	string	Frase completa que indica para onde o código será enviado e inclui o telefone ou e-mail parcialmente mascarado parcialmente mascarado. O texto exato pode variar.

Código de Resultado do Serviço

O serviceResultCode indica o resultado geral da execução do serviço:

serviceResultCode	Descrição	Código HTTP
200	A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente.	200

Exemplo de resposta

{
  "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***[email protected]"
      },
      {
        "method": "alternate_phone",
        "hint": "Sms with a verification code will be sent to your alternate phone number"
      }
    ]
  }
}

400 Requisição inválida

Erro retornado com o envelope do serviço (serviceResultCode reflete o código HTTP da resposta):

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

502 Gateway inválido

É retornado quando o serviço está temporariamente indisponível ou sua resposta não pôde ser interpretada. O corpo usa o envelope do serviço com serviceResultCode: 500:

{
  "serviceResultCode": 500,
  "serviceResultLog": "Serviço temporariamente indisponível. Tente novamente mais tarde",
  "serviceTime": "3000",
  "serviceTransactionId": "38de2932-0f2h-7gff-14g0-597h04161632"
}

504 Tempo esgotado no gateway

Erro de Timeout, retornado com o envelope do serviço:

{
  "serviceResultCode": 504,
  "serviceResultLog": "Timeout da solicitação. Tente novamente",
  "serviceTime": "30000",
  "serviceTransactionId": "48ef3043-1g3i-8hgg-25h1-608i15272743"
}

Os erros de autenticação (401/403) são rejeitados pelo gateway antes de chegar ao serviço e não usam o envelope serviceResultCode. Os erros de validação da plataforma usam o formato application/problem+json. Consulte Tratamento de erros para ver os detalhes das três formas de resposta.