Callbacks and status - Onboarding

We can configure up to two callback URLs — please inform the Pay2Free team which endpoints should be used.

How do the callbacks work?

We send callbacks to the configured endpoints with information about the user's current step in the flow.

🚧

Pay2Free provides an API key that is essential for validating incoming callbacks. It is strictly important to verify that the received API key matches the one provided.

First, let's understand: Onboarding status

Our flow has two statuses: Onboarding Status and Verification Status.

status_verification	status_onboarding
requested	requested	When the user accesses the liveness URL or restarts the flow
processing	front_document_sent	When the user submitted the front side of the document
processing	verse_document_sent	When the user submitted the back side of the document
processing	document_completed	When the user's document is validated
failed	failed_document	When the user's document is invalid
processing	selfie_sent	When the user submitted the selfie
failed	failed_selfie	When the user's selfie identification failed
completed	selfie_completed	When the user's selfie identification was completed successfully
manual_approve_pending	selfie_sent	When the process is under analysis
manual_approved	selfie_sent	Manually approved on the Pay2Free platform
manual_refused	selfie_sent	Manually rejected on the Pay2Free platform

📘

understanding the manual_approve_pending status.

When a user enters in review process, it takes up to three minutes to complete.

After this review, the system may or may not validate the user’s identity, resulting in one of the following two possible outcomes:

status_verification	status_onboarding
failed	failed_selfie
completed	selfie_completed

🤔 You might be wondering… When does a user receive the manual_approved or manual_refused status? ( Opcional)

We may enable a blocking rule for failed attempts — check the Settings section Click here to learn more

You can define how many times a user is allowed to fail after retrying the flow. For example, if it’s set to allow up to three failed attempts, once the user reaches that limit, they will be blocked. At that point, a manual review will be required by an operator through the Pay2Free platform, who will then approve or reject the onboarding process for that CPF.

Onboarding Callbacks

Callbacks will be send as the user progresses through the onboarding flow, with only the status_verification and status_onboarding fields being updated with the following content:

JSON

{
 "correlation_id":"9876543",
 "transaction_id":"847656ee-9cf7-4322-b3db-887aad303a1e",
  "document":"70469605006",
  "createdAt":"2025-03-13T13:19:57.641Z",
  "updatedAt":"2025-04-10T19:51:23.310Z",
  "status_onboarding":"selfie_completed",
  "status_verification":"completed",
  "event":"onboarding",
  "type":"onboarding"
 }

KYC Callback (Optional)

Another configuration we can enable is to send the KYC information via callback only after the user completes the process. If you prefer this option, please contact the Pay2Free team.

📘

IMPORTANT

When this setting is enabled, KYC information for the CPF will no longer be returned through the /kyc-liveness endpoint, as explained in the corresponding section

JSON

{
 "correlation_id":"9876543",
 "transaction_id":"847656ee-9cf7-4322-b3db-887aad303a1e",
  "document":"70469605006",
  "createdAt":"2025-03-13T13:19:57.641Z",
  "updatedAt":"2025-04-10T19:51:23.310Z",
  "status_onboarding":"completed",
  "status_verification":"selfie_completed",
  "event":"onboarding",
  "type":"kyc",
   "kyc": {
        "cpf": "70469605006",
        "name": "VALENTINA SILVA",
        "is_under_18": false,
        "status": "REGULAR",
        "status_code": 0,
        "date_death": null,
        "is_pep": false,
        "response_at": "2025-04-11T15:14:29.909Z",
        "response_token_validation": "9d07c605a783d98ac68c2a5542a1cf9af92f3f21",
        "mother_name": "MARIA SILVA",
        "birth_date": "2000-09-12T00:00:00.000Z",
        "age": 24,
        "internal_status": "ATIVO",
        "internal_status_code": 4,
        "address": {
            "street": "RUA EXEMPLO",
            "number": "123",
            "complement": "CASA 4",
            "neighborhood": "CENTRO",
            "city": "SAO PAULO",
            "state": "SP",
            "zip_code": "01000000",
            "country": ""
        },
        "gender": "F"
    }
  
 }