Ir para o conteúdo

Webhooks e API

Nosso processo de validação de identidade consiste em duas etapas para verificar a identidade do usuário, e deve ser concluído em até 20 minutos.

Uma vez que a validação esteja completa, enviaremos uma notificação por webhook para o seu sistema com os resultados da validação. Você também pode recuperar os resultados detalhados da validação usando nossa API.

Configurando o Webhook

Para garantir a segurança e integridade do nosso sistema, a configuração e gestão de webhooks e tokens são exclusivamente realizadas por operadores autorizados. Se você precisar de um webhook ou token, por favor, envie uma solicitação através dos canais designados, e nossa equipe o auxiliará na obtenção das credenciais necessárias.

Exemplo de Payload do Webhook: 

{
    "id": "5169bc58-5777-472b-8eb6-8bb660d62812",
    "document": "12345678910",
    "approved": true,
    "status": "APPROVED",
    "merchant_id": "3da83a2e-92f7-4e6c-b799-84cf84b6ab8b"
}

Status do Webhook

Os valores no status estão relacionados à comparação entre a foto do documento fornecido e a selfie. Confira nossos possíveis valores de retorno no campo status.

{
    "APPROVED"
    "REPROVED"
    "EXPIRED"
    "ERROR"
}

API para Recuperar Informações

Você pode recuperar resultados detalhados da validação usando nossa API.

Endpoint

GET https://shield.paag.io/api/identity-validation/{id}

Deve-se utilizar o mesmo token de acesso da SDK no campo Authorization.

Exemplo de Resposta Bem-Sucedida

HTTP Status: 200

Corpo da Resposta: 

{
  "id": "2b8f373-c462-4bbf-9a4f-8aeb7d71ec53",
  "status": "APPROVED/REPROVED/EXPIRED/ERROR",
  "session_type": "FULL_VALIDATION, OCR, FACEMATCH",
  "created_at": "2022-09-08T22:10:14.816Z",
  "reason": {
    "status": "CPF_DIFFERENT/...",
    "message": "Rosto não condizente com o documento/Documento não pertence a esse CPF..."
  },
  "ocr": {
    "type": "cnh",
    "back": "https://example.com/image-back.jpg",
    "front": "https://example.com/image-front.jpg"
  },
  "liveness": {
    "confidence": 0.86
  },
  "facematch": {
    "selfie": "https://example.com/selfie.jpg",
    "similarity": 0.90
  },
  "document":"12345678910"
}

Exemplo de Resposta com Dados Opcionais

Quando uma informação não está disponível, o campo correspondente será retornado como null.

HTTP Status: 200

Corpo da Resposta: 

{
  "id": "cc9f2da9-af85-423e-b61c-f6f06685530a",
  "status": "EXPIRED",
  "session_type": "FULL_VALIDATION",
  "createdAt": "2022-09-08T22:10:14.816Z",
  "reason": {
    "status": "DOCUMENT_WITHOUT_PHOTO",
    "message": "Documento sem foto"
  },
  "ocr": {
    "type": "RG",
    "back": "https://example.com/image-back.jpg",
    "front": "https://example.com/image-front.jpg"
  },
  "liveness": null,
  "facematch": null,
  "document":"12345678910"
}

Recurso Não Encontrado

Caso a validação solicitada não seja encontrada, a API retornará um HTTP Status: 404 com uma mensagem explicativa. Isso indica que o id fornecido não corresponde a uma sessão existente.

HTTP Status: 404

Corpo da Resposta: 

{
  "detail": "Identity validation session not found"
}

Tratamento de Erros

Se não conseguirmos nos comunicar com o seu webhook, faremos 5 tentativas. O usuário pode iniciar uma nova validação durante esse período. Portanto, recomendamos considerar o id recebido de cada validação e sempre referenciá-lo.