Comprovante NIN

Verifique o Número de Identificação Nacional (NIN) da Nigéria, assim como NIN Verify e, adicionalmente, gera uma cópia em PDF do NIN slip do titular.

A geração do PDF é assíncrona: a resposta inicial inclui um objeto pdf com um jobId e o estado processing. O cliente deve consultar o estado do trabalho por meio do endpoint de consulta até que o estado seja completed, momento em que é retornada a URL de download do PDF. Observe que no no Sandbox não é retornado o campo pdf; aparece apenas no modo live (veja a nota abaixo).

Endpoint

POST /kyc/nga/nin/slip

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
nin	string	Sim	Número de Identificação Nacional de 11 dígitos.

Exemplo de solicitação

{
  "nin": "09876543212"
}

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 NIN e o estado de geração do PDF. Veja a tabela abaixo.

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
nin	string	Número de Identificação Nacional.
title	string	Título do titular.
firstname	string	Nome(s) do titular.
middlename	string	Nome do meio.
surname	string	Sobrenome(s) do titular.
birthdate	string	Data de nascimento.
birthcountry	string	País de nascimento.
birthstate	string	Estado de nascimento.
birthlga	string	Área de Governo Local (LGA) de nascimento.
gender	string	Gênero.
maritalstatus	string	Estado civil.
heigth	string	Altura em centímetros. O campo se chama literalmente heigth (sic): a ortografia é preservada exatamente como é recebida; não usar height.
email	string	E-mail registrado.
telephoneno	string	Número de telefone registrado.
residence_address	string	Endereço de residência.
residence_state	string	Estado de residência.
residence_lga	string	Área de Governo Local (LGA) de residência.
residence_town	string	Cidade de residência.
residencestatus	string	Status de residência.
self_origin_state	string	Estado de origem.
self_origin_lga	string	Área de Governo Local (LGA) de origem.
self_origin_place	string	Local de origem.
profession	string	Profissão.
educationallevel	string	Nível de escolaridade.
employmentstatus	string	Situação de emprego.
religion	string	Religião.
spoken_language	string	Idioma principal falado.
ospokenlang	string	Outro(s) idioma(s) falado(s).
nok_firstname	string	Nome do parente de contato (parente próximo).
nok_middlename	string	Segundo nome do parente de contato.
nok_surname	string	Sobrenome do parente de contato.
nok_address1	string	Endereço (linha 1) do parente de contato.
nok_address2	string	Endereço (linha 2) do parente de contato.
nok_town	string	Cidade do parente de contato.
nok_lga	string	Área de Governo Local (LGA) do parente de contato.
nok_state	string	Estado do parente de contato.
nok_postalcode	string	Código postal do parente de contato.
pfirstname	string	Nome anterior do titular (se existir; normalmente vazio).
pmiddlename	string	Segundo nome anterior do titular (se existir; normalmente vazio).
psurname	string	Sobrenome anterior do titular (se existir; normalmente vazio).
photo	string	Foto do titular em formato Base64.
signature	string	Assinatura do titular em formato Base64.
userid	string	Identificador interno de usuário.
vnin	string	NIN virtual (vNIN) do titular.
central_iD	string	Identificador central do registro. O campo se chama literalmente central_iD (sic).
tracking_id	string	Identificador de rastreamento do registro.
pdf	object	Status de geração do NIN slip em PDF. Presente apenas no modo live. Veja a tabela abaixo.

Parâmetros de resposta — data.pdf

Parâmetro	Tipo	Descrição
jobId	string	Identificador do trabalho de geração do PDF. É usado para consultar o status.
status	string	Status da geração. Valores possíveis: processing, completed.

Nota: em no Sandbox não é retornado o campo pdf (confirmado empiricamente em 13-07-2026); nesse caso não há jobId nada a consultar. No modo live, o objeto pdf (jobId, status) permite fazer polling do status por meio de GET /kyc/nga/nin/slip/{jobId}. Existem tenants de produção com credenciais live; a confirmação do ciclo completo do PDF em live requer uma consulta com um NIN real e será realizada como parte da validação de QA com um tenant live.

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 (modo live)

{
  "serviceResultCode": 200,
  "serviceTime": "2100",
  "serviceResultLog": "Success",
  "serviceTransactionId": "b18e902f-01f9-8e0i-e53e-9f3589eg99gh",
  "data": {
    "nin": "09876543212",
    "title": "mr",
    "firstname": "JOHN",
    "middlename": "PAUL",
    "surname": "DOE",
    "birthdate": "15-01-1990",
    "birthcountry": "nigeria",
    "birthstate": "Lagos",
    "birthlga": "Lagos Island",
    "gender": "m",
    "maritalstatus": "single",
    "heigth": "175",
    "email": "[email protected]",
    "telephoneno": "08012345678",
    "residence_address": "123 Main Street, Lagos",
    "residence_state": "Lagos",
    "residence_lga": "Ikeja",
    "residence_town": "Ikeja",
    "residencestatus": "birth",
    "self_origin_state": "Lagos",
    "self_origin_lga": "Lagos Island",
    "self_origin_place": "Lagos",
    "profession": "Engineer",
    "educationallevel": "tertiary",
    "employmentstatus": "employed",
    "religion": "christianity",
    "spoken_language": "YORUBA",
    "ospokenlang": "ENGLISH",
    "nok_firstname": "JANE",
    "nok_middlename": "",
    "nok_surname": "DOE",
    "nok_address1": "123 Main Street",
    "nok_address2": "",
    "nok_town": "Ikeja",
    "nok_lga": "Ikeja",
    "nok_state": "Lagos",
    "nok_postalcode": "100001",
    "pfirstname": "JOHN",
    "pmiddlename": "PAUL",
    "psurname": "DOE",
    "photo": "base64encodedphoto...",
    "signature": "base64encodedsignature...",
    "userid": "",
    "vnin": "AB012345678901234YZ",
    "central_iD": "12345678",
    "tracking_id": "ABC123DEF456GH",
    "pdf": {
      "jobId": "4",
      "status": "processing"
    }
  }
}

Consultar status do PDF

Consulte o status do trabalho de geração do NIN slip em PDF a partir do jobId obtido na resposta anterior. Recomenda-se consultar o status a cada poucos segundos até que seja completed.

Nota: a URL de download do PDF expira em 7 dias após sua geração. Baixe e armazene o documento antes desse prazo.

Endpoint

GET /kyc/nga/nin/slip/{jobId}

Autenticação

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

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
jobId	string	Sim	ID do trabalho de geração obtido na resposta do POST.

Exemplo de solicitação

GET /kyc/nga/nin/slip/4

Respostas

200 Sucesso

Parâmetros de resposta — data

Parâmetro	Tipo	Descrição
id	string	Identificador do trabalho de geração.
status	string	Status da geração. Valores possíveis: processing, completed.
url	string	URL de download do PDF. Presente apenas quando status é completed. Expira em 7 dias.

Exemplo de resposta — em processamento

{
  "serviceResultCode": 200,
  "serviceTime": "120",
  "serviceResultLog": "Success",
  "serviceTransactionId": "c29f013g-12g0-9f1j-f64f-0g4690fh00hi",
  "data": {
    "id": "4",
    "status": "processing"
  }
}

Exemplo de resposta — concluído

{
  "serviceResultCode": 200,
  "serviceTime": "110",
  "serviceResultLog": "Success",
  "serviceTransactionId": "d30g124h-23h1-0g2k-g75g-1h5701gi11ij",
  "data": {
    "id": "4",
    "status": "completed",
    "url": "https://files.example.com/nin-slips/4/nin-slip.pdf"
  }
}

Respostas de erro

Os seguintes erros se aplicam a ambos endpoints:

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.