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",
  "webhook_url": "https://seu-servidor.com/webhook/kyc",
  "transaction_id": "48663425-69fe-4ae9-baae-82ede29d0668"
}

Parâmetros:

• cpf: CPF a ser consultado (string, apenas números)
• integration_id: ID da integração obtido no dashboard
• webhook_url: (Opcional) URL que receberá o webhook
• transaction_id: (Opcional) ID da transação para rastreamento

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://face.pixtopay.com.br/?guid=<ONBOARDING_ID>
  2. Para integração direta via API: Utilize como token de autorização (onboarding_id) nos próximos endpoints do fluxo de onboarding

Gerar link para onboarding (/links/generate)

Gera link para ser utilizado no onboarding

Método: POST

Body:

{
  "cpf": "12345678901",
  "integration_id": "b64d523c-8c93-4188-b5f6-3f5f08397712",
  "webhook_url": "https://seu-servidor.com/webhook/kyc",
  "transaction_id": "48663425-69fe-4ae9-baae-82ede29d0668"
}

Parâmetros:

• cpf: CPF a ser consultado (string, apenas números)
• integration_id: ID da integração obtido no dashboard
• webhook_url: (Opcional) URL que receberá o webhook
• transaction_id: (Opcional) ID da transação para rastreamento

Resposta:

{
  "guid": "8d9b6f1f-fad1-4d96-88f6-e42334b8c3c1",
  "redirect_url": "https://face.pixtopay.com.br/?guid=8d9b6f1f-fad1-4d96-88f6-e42334b8c3c1"
}

Campos da resposta:

• message: Mensagem de conclusão da operação
• redirect_url: URL para redirecionar o usuário para o 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

Endpoints de Integração

Estes endpoints permitem recuperar dados de submissão e imagens associadas às suas integrações.

Autenticação (Dashboard API Key)

Todos os endpoints abaixo requerem autenticação via chave de API de dashboard.
Essa chave pode ser obtida no dashboard da PixToPay.

Header: Authorization: Bearer <SUA_CHAVE_API>

Listar submissões (GET /submissions/all)

Recupera uma lista paginada de submissões associadas às suas integrações, com filtros por CPF, nome, status e período.
Este é o endpoint ideal para encontrar um usuário e, a partir disso, localizar a submission_id para download das imagens.

Método: GET
URL: /submissions/all

Headers:

Authorization: Bearer <SUA_DASHBOARD_API_KEY>

Parâmetros de query:

Exemplo de resposta:

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "customer_id": "987fcdeb-51a2-43d1-a456-426614174000",
      "tax_id_number": "000.000.000-72",
      "name": "João da Silva",
      "type": "onboarding",
      "integration": "Minha Integração Principal",
      "integration_id": "c1b2d3e4-f567-8901-2345-6789abcdef01",
      "status": "approved",
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T10:05:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Consultar um onboarding e suas submissões (GET /onboarding/:id)

Caso você já tenha o onboarding_id (por exemplo, recebido no webhook), pode consultar todo o contexto do cliente, incluindo as submissões e webhooks relacionados.

Método: GET
URL: /onboarding/:id

Parâmetros de caminho:

Parâmetros de query:

A resposta inclui, entre outros campos, dois arrays importantes:

• submissions: lista de submissões associadas ao onboarding (já com URLs assinadas das imagens)
• webhooks: eventos de webhook vinculados àquele onboarding

Fluxo recomendado quando você recebe um webhook:

1. Receba o webhook contendo onboarding_id, integration_id e transaction_id.
2. Chame GET /onboarding/{onboarding_id}?integration_id={integration_id} com a Dashboard API Key.
3. Use o array submissions da resposta para:
   • Identificar a submissão relevante (por status, data ou tipo).
   • Obter diretamente as URLs assinadas de selfie, front_document e back_document quando disponíveis.

Obter todas as imagens de uma submissão (GET /submissions/:submission_id/images)

Recupera todas as imagens (frente, verso e selfie) associadas a uma submissão em uma única chamada.

Método: GET
URL: /submissions/:submission_id/images

Parâmetros de caminho:

Exemplo de resposta:

{
  "back_document_url": "https://s3.amazonaws.com/.../back_document",
  "front_document_url": "https://s3.amazonaws.com/.../front_document",
  "selfie_url": "https://s3.amazonaws.com/.../selfie"
}

Obter uma imagem específica da submissão (GET /submissions/:submission_id/:type)

Quando você precisa apenas de uma imagem específica de uma submissão:

Método: GET
URL: /submissions/:submission_id/:type

Parâmetros de caminho:

Exemplo de resposta:

{
  "url": "https://s3.amazonaws.com/.../selfie"
}

Resumo do fluxo para “achar usuário e baixar imagens”

• Para encontrar o usuário: use GET /submissions/all com filtros de cpf, search (nome), status e intervalo de datas.
• Para baixar imagens a partir de um webhook: use o onboarding_id do webhook em GET /onboarding/:id, escolha a submissão desejada no array submissions e então:
  • Use diretamente as URLs assinadas retornadas, ou
  • Chame GET /submissions/:submission_id/images / GET /submissions/:submission_id/:type conforme sua necessidade.