Skip to content

Webhooks and API

Our identity validation process consists of two steps to verify the user's identity, and it must be completed within 20 minutes.

Once the validation is complete, we will send a webhook notification to your system with the validation results. You can also retrieve detailed validation results using our API.

Setting up the webhook

To ensure the security and integrity of our system, the setup and management of webhooks and tokens are exclusively handled by authorized operators. If you require a webhook or token, please submit a request through the designated channels, and our team will assist you in obtaining the necessary credentials.

Example of Webhook Payload: 

{
    "id": "5169bc58-5777-472b-8eb6-8bb660d62812",
    "document":"12345678910",
    "approved": true,
    "status": "APPROVED"
}

Webhook Status

The values in the status field are related to the comparison between the document photo provided and the selfie. Check the possible return values below:

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

API to retrieve information

You can retrieve detailed validation results using our API. The API endpoint is as follows:

Endpoint

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

You must use the same SDK access token in the Authorization field.

Example of Successful Response

HTTP Status: 200

Response Body: 

{
  "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"
}

Example of Response with Optional Fields

When a piece of information is not available, the corresponding field will be returned as null.

HTTP Status: 200

Response Body: 

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

Not Found Resource

If the requested validation is not found, the API will return an HTTP Status: 404 with an explanatory message. This indicates that the id provided does not correspond to an existing session.

HTTP Status: 404

Response Body: 

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

Error Handling

If we are unable to communicate with your webhook, we will make 5 attempts. The user can start a new validation during this time. Therefore, we recommend considering the id received from each validation and always referring to it.