Como usar a API

Configuração Inicial

Para utilizar a API diretamente (sem iframe), utilize a seguinte URL base:

https://kyc-api.pixtopay.com.br

Consulta de Dados do Cliente

Autenticação: Todas as requisições de consulta devem incluir um token de autorização no header Authorization, obtido no dashboard da plataforma.

Pré-registro (/customer/preregister) (Opcional)

Este endpoint é opcional. Você pode consultar diretamente o endpoint de registro (/customer/register) para fazer a integração diretamente e já obter o onboarding_id necessário para prosseguir com o fluxo.

Consulta informações básicas de uma pessoa física.

Método: POST

Body:

{
  "cpf": "12345678901",
  "integration_id": "b64d523c-8c93-4188-b5f6-3f5f08397712"
}

Parâmetros:

• cpf: CPF a ser consultado (string, apenas números)
• integration_id: ID da integração obtido no dashboard

Resposta:

{
  "birth_date": "1990-01-01",
  "deceased": false,
  "first_name": "João",
  "surname": "Silva",
  "is_pep": false
}

Campos da resposta:

• birth_date: Data de nascimento (formato: YYYY-MM-DD)
• deceased: Indica se a pessoa é falecida
• first_name: Primeiro nome
• surname: Último nome
• is_pep: Indica se a pessoa é politicamente exposta (PEP)

Registro do Cliente

Criar/Atualizar Registro (/customer/register)

Registra ou atualiza o cadastro de uma pessoa no sistema.

Método: POST

Body:

{
  "cpf": "12345678901",
  "integration_id": "b64d523c-8c93-4188-b5f6-3f5f08397712"
}

Resposta:

{
  "message": "Operação concluída com sucesso",
  "onboarding_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Campos da resposta:

• message: Mensagem de conclusão da operação
• onboarding_id: ID do onboarding criado/atualizado (UUID). Este ID pode ser utilizado de duas formas:
  1. Para integração via iframe: Utilize este UUID no template do link: https://kyc-front.pixtopay.com.br/?onboarding_id=<ONBOARDING_ID>
  2. Para integração direta via API: Utilize como token de autorização nos próximos endpoints do fluxo de onboarding

Fluxo de Onboarding

Autenticação: Todas as requisições KYC devem incluir um onboarding_id no header Authorization, obtido na request de registro.

1. Upload de Imagens (/onboarding/upload)

Realiza o upload das imagens do documento e selfie do usuário.

Método: POST

Headers:

{
  "Authorization": "<ONBOARDING_ID>"
}

Query Parameters:

• type: Tipo de imagem a ser enviada
  • "front_document": Frente do documento
  • "back_document": Verso do documento
  • "selfie": Foto selfie

Exemplo de requisição:

POST /onboarding/upload?type=front_document

Resposta:

{
  "message": "Upload realizado com sucesso"
}

2. Submeter para Avaliação (/onboarding/submit)

Após enviar todas as imagens necessárias, submete os dados para análise.

Método: POST

Headers:

{
  "Authorization": "<ONBOARDING_ID>"
}

Body:

{
  "lat": -23.5505,
  "lng": -46.6333
}

Parâmetros:

• lat: Latitude da localização do usuário
• lng: Longitude da localização do usuário

Resposta:

{
  "guid": "abc123def456",
  "matches": true,
  "similarity": 0.95,
  "status": "approved",
  "reason": "Documentos válidos e selfie compatível",
  "show_full_results": true,
  "frontImageSize": 1024000,
  "selfieImageSize": 512000
}

Campos da resposta:

• guid: Identificador único da submissão
• matches: Indica se houve correspondência entre documento e selfie
• similarity: Índice de similaridade (0 a 1)
• status: Status da avaliação
• reason: Motivo/detalhes do resultado em caso de erro
• show_full_results: Indica se resultados completos estão disponíveis
• frontImageSize: Tamanho da imagem frontal em bytes
• selfieImageSize: Tamanho da imagem selfie em bytes

Fluxo de Validação Facial (Liveness)

1. Upload de Selfie (/onboarding/upload)

Realiza o upload de uma nova selfie para validação de vivacidade.

Método: POST

Headers:

{
  "Authorization": "<ONBOARDING_ID>"
}

Query Parameters:

?type=selfie

Resposta:

{
  "message": "Upload realizado com sucesso"
}

Observações importantes:

• O onboarding da pessoa deve estar concluído antes desta etapa
• Este endpoint aceita apenas uploads do tipo "selfie"

2. Verificar Face (/onboarding/verify)

Verifica se a selfie enviada corresponde aos dados cadastrados.

Método: POST

Headers:

{
  "Authorization": "<ONBOARDING_ID>"
}

Resposta:

{
  "matches": true,
  "similarity": 0.92,
  "similarityThreshold": 0.85,
  "message": "Verificação facial aprovada"
}

Campos da resposta:

• matches: Indica se a face corresponde ao cadastro
• similarity: Índice de similaridade obtido (0 a 1)
• similarityThreshold: Limiar mínimo de similaridade requerido
• message: Mensagem descritiva do resultado