Liveness

Second Step: Request liveness URL

curl

curl --location '<API_BASE_URL>/kyc-liveness/:document' \
--header 'Authorization: '' \
--header 'Content-Type: application/json' \
--data '{
    "correlation_id": "",
    "plan": "",
    "event": "",
    "redirectUrl": ""
}'

Header

Content-Type	application/json
Authorization	Token

To obtain the authorization token Click here to learn more

Route parameters

document	CPF

Body

correlationId (string)	mandatory	it’s must be unic for each request
plan ( enum )	mandatory	plan_basic | plan_standard | plan_premium | plan_plus | plan_full
event (string)	mandatory	It is a way to identify where the liveness process was triggered. Example: personal_data_change.
redirectUrl	optional	The URL to which the user should be redirected after completing the process. Example: https://yourwebsite/user-personal-info You only need to pass the path, starting with a forward slash: /user-personal-info

Data for testing

🚧

IMPORTANT

In the sandbox environment, the onboarding process will always result in the status manual_approve_pending. To test other types of results, you can inform the Pay2Free team of, the CPF and the desired outcome. Otherwise, you can use the following CPFs:

CPF	Result
70469605006	will be approved during onboarding and will always pass biometric verification
72025413009	will be approved during onboarding and will always fail biometric verification
06165131000	will always be rejected during onboarding

Responses

200

json

{
    "correlation_id": "23424232",
    "transaction_id": "8313b1f1-4858-4201-8b56-fcf9b76f86ab",
    "status_onboarding": "requested",
    "status_verification": "requested",
    "event": "personal_data_change",
    "action": {
        "url": "<LIVENESS_BASE_URL>",
        "qrcode": "<QRCODE>",
        "type": "onboarding"
    },
    "url_callback": {
        "sent": [
            {
                "url": "<YOUR__CALLBACK_URL>",
                "correlation_id": "23424232"
            }
        ]
    },
    "datetime": "2025-04-11T15:14:30.400Z",
    "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"
    }
}

correlationId (string) *	The correlationId passed in the request body
transactionId ( string ) *	A unique Pay2Free identifier for the request
status_onboarding ( enum )	The current step the user is on in the flow.
status_verification ( enum ) *	requested | processing | completed | failed | manual_approve_pending | manual_approved | manual_refused
event ( string ) *	The event passed in the request body
action.url (string) *	The URL where the user will start the liveness process
action.qrcode (string) *	The QR code that returns the URL where the user will start the liveness proces
action.type (enum ) *	onboarding | biometric_identification
url_callback (string) *	The URLs where we will send the callbacks
kyc (object)	CPF KYC information

400 - Obit or Under age

JSON

{
    "statusCode": 400,
    "message": [
        "CPF must be valid"
    ],
    "error": "Bad Request"
}

400 - Invalid CPF or Not found

JSON

{
    "document": "06165130",
    "message": "O documento solicitado não está em um formato válido.",
    "code": "INVALID_DOCUMENT",
    "response_at": "2024-05-28T20:30:27.440Z",
    "response_token_validation": "4ysv8ScY16D0GHY7Q6miEAbVtorf57blUMWPHLsO46cmezqE4PCEGbkxE3HwfQjm"
}

📘

💡 The action.url expires in 30 minutes or upon process completion. You can reuse the same URL only if the user hasn't completed the process and the 30-minute window hasn't expired.

Note that action.type can be either onboarding or biometric_identification. Once the user completes the onboarding flow, the next call to the /kyc-liveness route will return type: biometric_identification.

Thrid Step: Callbacks and Status

Callbacks and Status - onboarding
Callbacks and Status - Biometric Identification

Handled on the frontend

postMessage
For integrations via iframe:
If the URL is used outside the platform, redirection and communication will be handled through the redirectUrl parameter.