How to use the API

Initial Setup

To use the API directly (without iframe), use the following base URL:

https://kyc-api.pixtopay.com.br

Customer Data Query

Authentication: All query requests must include an authorization token in the Authorization header, obtained from the platform dashboard.

CPF Lookup (/customer/cpf)

Looks up a CPF using only the basic_data dataset, saves (or reuses) the customer in PixToPay's database, and returns already formatted data.

Method: POST

Body:

{
  "cpf": "12345678901"
}

Parameters:

• cpf: CPF to query (string, accepts with or without mask)

Response:

{
  "tax_id_number": "12345678901",
  "tax_id_country": "BR",
  "social_security_number": null,
  "name": "João da Silva",
  "common_name": null,
  "standardized_name": "JOAO DA SILVA",
  "gender": "M",
  "name_word_count": 3,
  "number_of_fullname_namesakes": 1,
  "name_uniqueness_score": 0.94,
  "first_name_uniqueness_score": 0.88,
  "first_and_last_name_uniqueness_score": 0.91,
  "birth_date": "1990-01-01",
  "age": 35,
  "zodiac_sign": "Capricorn",
  "chinese_sign": "Horse",
  "birth_country": "Brazil",
  "mother_name": "Maria da Silva",
  "father_name": "José da Silva",
  "tax_id_status": "REGULAR",
  "tax_id_origin": "RECEITA FEDERAL",
  "tax_id_fiscal_region": "SP",
  "has_obit_indication": false,
  "tax_id_status_date": "2024-01-01T00:00:00.000Z",
  "tax_id_status_registration_date": "2010-01-01T00:00:00.000Z"
}

Response fields:

• tax_id_number, tax_id_country: tax document and fiscal country
• name, common_name, standardized_name, gender: person identity fields
• birth_date, age, zodiac_sign, chinese_sign, birth_country: birth information
• mother_name, father_name: parent names
• tax_id_status, tax_id_origin, tax_id_fiscal_region, tax_id_status_date, tax_id_status_registration_date: CPF tax status information
• name_word_count, number_of_fullname_namesakes, name_uniqueness_score, first_name_uniqueness_score, first_and_last_name_uniqueness_score: name composition/uniqueness metrics
• social_security_number, has_obit_indication: complementary basic_data fields

Pre-registration (/customer/preregister) (Optional)

This endpoint is optional. You can directly query the registration endpoint (/customer/register) to integrate directly and obtain the onboarding_id needed to proceed with the flow.

Queries basic information about an individual.

Method: POST

Body:

{
  "cpf": "12345678901",
  "integration_id": "b64d523c-8c93-4188-b5f6-3f5f08397712"
}

Parameters:

• cpf: CPF to be queried (string, numbers only)
• integration_id: Integration ID obtained from the dashboard

Response:

{
  "birth_date": "1990-01-01",
  "deceased": false,
  "first_name": "João",
  "surname": "Silva",
  "is_pep": false
}

Response fields:

• birth_date: Date of birth (format: YYYY-MM-DD)
• deceased: Indicates whether the person is deceased
• first_name: First name
• surname: Last name
• is_pep: Indicates whether the person is a politically exposed person (PEP)

Customer Registration

Create/Update Registration (/customer/register)

Registers or updates a person's record in the system.

Method: 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"
}

Parameters:

• cpf: CPF to be queried (string, numbers only)
• integration_id: Integration ID obtained from the dashboard
• webhook_url: (Optional) URL that will receive the webhook
• transaction_id: (Optional) Transaction ID for tracking

Response:

{
  "message": "Operação concluída com sucesso",
  "onboarding_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response fields:

• message: Operation completion message
• onboarding_id: Created/updated onboarding ID (UUID). This ID can be used in two ways:
  1. For iframe integration: Use this UUID in the link template: https://face.pixtopay.com.br/?guid=<ONBOARDING_ID>
  2. For direct API integration: Use as the authorization token (onboarding_id) in the next onboarding flow endpoints

Generate onboarding link (/links/generate)

Generates a link to be used in onboarding.

Method: 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",
  "flow": "onboarding"
}

Parameters:

• cpf: CPF to be queried (string, numbers only)
• integration_id: Integration ID obtained from the dashboard
• webhook_url: (Optional) URL that will receive the webhook
• transaction_id: (Optional) Transaction ID for tracking
• flow: (Optional) Flow type: "onboarding" (default) or "liveness"

transaction_id behavior per flow:

• onboarding flow: the transaction_id is associated with the onboarding link and is sent in all events for that onboarding (document, selfie, analysis, success/failure).
• liveness flow: the transaction_id is stored in the submission for that liveness journey and will be sent in the face_match_start, face_match_success, and face_match_error webhooks for that same journey. The onboarding link and the onboarding's transaction_id are not changed.

Response:

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

Response fields:

• message: Operation completion message
• redirect_url: URL to redirect the user to the onboarding.

Onboarding Flow

Authentication: All KYC requests must include an onboarding_id in the Authorization header, obtained from the registration request.

1. Image Upload (/onboarding/upload)

Uploads the user's document images and selfie.

Method: POST

Headers:

{
  "Authorization": "<ONBOARDING_ID>"
}

Query Parameters:

• type: Type of image to be uploaded
  • "front_document": Front of the document
  • "back_document": Back of the document
  • "selfie": Selfie photo

Request example:

POST /onboarding/upload?type=front_document

Response:

{
  "message": "Upload realizado com sucesso"
}

2. Submit for Evaluation (/onboarding/submit)

After sending all required images, submits the data for analysis.

Method: POST

Headers:

{
  "Authorization": "<ONBOARDING_ID>"
}

Body:

{
  "lat": -23.5505,
  "lng": -46.6333
}

Parameters:

• lat: User's location latitude
• lng: User's location longitude

Response:

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

Response fields:

• guid: Unique submission identifier
• matches: Indicates whether there was a match between the document and selfie
• similarity: Similarity index (0 to 1)
• status: Evaluation status
• reason: Reason/details of the result in case of error
• show_full_results: Indicates whether full results are available
• frontImageSize: Front image size in bytes
• selfieImageSize: Selfie image size in bytes

Facial Validation Flow (Liveness)

1. Selfie Upload (/onboarding/upload)

Uploads a new selfie for liveness validation.

Method: POST

Headers:

{
  "Authorization": "<ONBOARDING_ID>"
}

Query Parameters:

?type=selfie

Response:

{
  "message": "Upload realizado com sucesso"
}

Important notes:

• The person's onboarding must be completed before this step
• This endpoint only accepts uploads of type "selfie"

2. Verify Face (/onboarding/verify)

Verifies whether the uploaded selfie matches the registered data.

Method: POST

Headers:

{
  "Authorization": "<ONBOARDING_ID>"
}

Response:

{
  "matches": true,
  "similarity": 0.92,
  "similarityThreshold": 0.85,
  "message": "Verificação facial aprovada"
}

Response fields:

• matches: Indicates whether the face matches the registered record
• similarity: Obtained similarity index (0 to 1)
• similarityThreshold: Minimum required similarity threshold
• message: Descriptive result message

Integration Endpoints

These endpoints allow you to retrieve submission data and images associated with your integrations.

Authentication (Dashboard API Key)

All endpoints below require authentication via dashboard API key. This key can be obtained from the PixToPay dashboard.

Header: Authorization: Bearer <YOUR_API_KEY>

List submissions (GET /submissions/all)

Retrieves a paginated list of submissions associated with your integrations, with filters by CPF, name, status, and date range. This is the ideal endpoint for finding a user and then locating the submission_id to download images.

Method: GET URL: /submissions/all

Headers:

Authorization: Bearer <YOUR_DASHBOARD_API_KEY>

Query parameters:

Response example:

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

Query an onboarding and its submissions (GET /onboarding/:id)

If you already have the onboarding_id (for example, received via webhook), you can query the full customer context, including related submissions and webhooks.

Method: GET URL: /onboarding/:id

Path parameters:

Query parameters:

The response includes, among other fields, two important arrays:

• submissions: list of submissions associated with the onboarding (already with signed image URLs)
• webhooks: webhook events linked to that onboarding

Recommended flow when you receive a webhook:

1. Receive the webhook containing onboarding_id, integration_id, and transaction_id.
2. Call GET /onboarding/{onboarding_id}?integration_id={integration_id} with the Dashboard API Key.
3. Use the submissions array from the response to:
   • Identify the relevant submission (by status, date, or type).
   • Directly obtain the signed URLs for selfie, front_document, and back_document when available.

Get all images from a submission (GET /submissions/:submission_id/images)

Retrieves all images (front, back, and selfie) associated with a submission in a single call.

Method: GET URL: /submissions/:submission_id/images

Path parameters:

Response example:

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

Get a specific image from the submission (GET /submissions/:submission_id/:type)

When you need only a specific image from a submission:

Method: GET URL: /submissions/:submission_id/:type

Path parameters:

Response example:

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

Summary of the flow to "find a user and download images"

• To find the user: use GET /submissions/all with filters for cpf, search (name), status, and date range.
• To download images from a webhook: use the onboarding_id from the webhook in GET /onboarding/:id, choose the desired submission from the submissions array, and then:
  • Use the signed URLs returned directly, or
  • Call GET /submissions/:submission_id/images / GET /submissions/:submission_id/:type as needed.