Sessions

A Session is a single execution instance of a Flow by a specific user (Customer). It tracks the user's progress through the steps, their input data, and the final result.

Lifecycle

1. PENDING: Session created, waiting for user input.
2. PROCESSING: User has submitted data, rules are running.
3. COMPLETED: Analysis finished. Outcome is available (Approved/Rejected/Review).
4. EXPIRED: User did not complete within the timeout (default 30 mins).

Creating a Session

Currently, Sessions are initiated in two ways:

1. Dashboard: You generate a unique link for a customer to complete checks.
2. Transactions (KYT): When you submit a Transaction, if the risk engine determines KYC is needed, a Session is automatically created and linked.

Public Session Access

The frontend application (or your mobile app) accesses the session configuration via:

Endpoint: GET /kyc-sessions/:id/public

Returns:

• steps: The UI steps to render.
• flowName: Name of the flow.
• branding: Your company's branding (Logo, Colors).

Completing a Session

When the user finishes the steps, the frontend submits the data:

Endpoint: POST /kyc-sessions/:id/complete

Payload:

{
  "userData": {
    "name": "User Name",
    "cpf": "123.456.789-00",
    "selfie_url": "..."
  }
}

Webhooks

When a session reaches a terminal state (Completed), a Webhook is fired to your configured endpoint.

Event: kyc.session.complete

{
  "type": "kyc.session.complete",
  "data": {
    "sessionId": "sess_123",
    "status": "COMPLETED",
    "customerId": "cust_abc",
    "riskScore": 10
  }
}