Detalhes do BVN

Consulta diretamente os dados completos do BVN (Bank Verification Number) da Nigéria sem o Fluxo de consentimento OTP. É uma alternativa ao Fluxo de verificação BVN em 3 etapas (BVN Initiate, BVN Send OTP, BVN Verify OTP) quando a validação por OTP do titular não é necessária.

Nota: cada solicitação é faturada mesmo que a consulta falhe. Recomenda-se validar o formato do BVN (11 dígitos numéricos) no lado do cliente antes de enviar a solicitação.

Endpoint

POST /kyc/nga/bvn/details

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.

Exemplo de solicitação

{
  "bvn": "12345678901"
}

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 completos do BVN. Ver tabela a seguir.

Parâmetros de resposta — data

Nota: o objeto data é retornado sem mapeamento nem normalização de campos. Os nomes e a ortografia dos campos são mantidos exatamente como são recebidos.

Parâmetro	Tipo	Descrição
bvn	string	Número de Verificação Bancária.
first_name	string	Nome(s) do titular.
middle_name	string	Nome do meio.
last_name	string	Sobrenome(s) do titular.
dob	string	Data de nascimento.
gender	string	Gênero.
email	string	Endereço de e-mail registrado.
phone_number	string	Número de telefone registrado.
phone_number_2	string	Número de telefone alternativo registrado.
address	string	Endereço de residência.
state_of_origin	string	Estado de origem.
lga_of_origin	string	Área de Governo Local (LGA) de origem.
lga_of_Residence	string	Área de Governo Local (LGA) de residência. O campo é chamado literalmente lga_of_Residence (sic): a ortografia é mantida exatamente como é recebida.
marital_status	string	Estado civil.
nin	string	Número Nacional de Identificação associado ao BVN.
nationality	string	Nacionalidade.
registration_date	string	Data de registro do BVN.
watch_listed	boolean	Indica se o titular consta na lista de vigilância.
photoId	string	Foto do titular em formato Base64.

Código de Resultado do Serviço

O serviceResultCode indica o resultado geral da execução do serviço e reflete o código de status HTTP da resposta:

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": "1400",
  "serviceResultLog": "Success",
  "serviceTransactionId": "e41h235i-34i2-1h3l-h86h-2i6812hj22jk",
  "data": {
    "bvn": "12345678901",
    "first_name": "JOHN",
    "middle_name": "PAUL",
    "last_name": "DOE",
    "dob": "15-Jan-1990",
    "gender": "Male",
    "email": "[email protected]",
    "phone_number": "08012345678",
    "phone_number_2": "08087654321",
    "address": "123 Main Street, Lagos",
    "state_of_origin": "Lagos State",
    "lga_of_origin": "Lagos Island",
    "lga_of_Residence": "Ikeja",
    "marital_status": "Single",
    "nin": "09876543212",
    "nationality": "Nigeria",
    "registration_date": "01-Mar-2015",
    "watch_listed": false,
    "photoId": "base64encodedphoto..."
  }
}

400 Requisição inválida

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

{
  "serviceResultCode": 400,
  "serviceResultLog": "Desculpe, a consulta falhou. Verifique os dados e tente novamente",
  "serviceTime": "151",
  "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.