Headless KYC Tier 3 Escalation

Breeze may escalate a customer's KYC tier to Tier 3 based on internal risk rules, which will require the customer to complete specific verifications on Persona, such as Government ID check, biometric verification, and a source of funds questionnaire. These verifications must be done via Persona web application and cannot be passed to Breeze via API.

For headless KYC integration, Breeze communicates this escalation as a webhook event to the merchant. It is the merchant's responsibility to retrieve the Persona KYC inquiry link from Breeze via API, and communicate this requirement with the customer. Failure to complete the KYC in time may result in the customer's payouts to be blocked.

High-Level Overview

The diagram below shows the high-level flow of the interaction between Breeze, the merchant, the customer being KYC-ed, and Persona.

Breeze uses Persona as its identity verification provider. Persona handles document checks, biometric verification, and sanctions screening on Breeze's behalf. The UI for Tier 3 KYC is entirely hosted on Persona with no Breeze branding.

sequenceDiagram
    participant Merchant
    participant Breeze
    participant Customer
    participant Persona

    Note over Breeze: KYC escalation event
    Breeze->>Merchant: HEADLESS_KYC_STATUS_UPDATED webhook
    Merchant-->>Breeze: 200 OK
    
    Note over Merchant: Retrieve Persona Link
    Merchant->>Breeze: POST /v1/headless_kyc/:id/initiate_tier_3_kyc
    Breeze-->>Merchant: Return Persona Link

    Note over Merchant: Communication
    Merchant->>Customer: Communicate KYC requirement with customer and share Persona link

    Note over Customer, Persona: Start KYC
    Customer->>Persona: Start KYC process

    Note over Breeze, Persona: KYC verification
    Breeze->>Persona: Retrieve KYC data
    Persona-->>Breeze: KYC result

    Note over Breeze: KYC updated event
    Breeze->>Merchant: HEADLESS_KYC_STATUS_UPDATED webhook
    Merchant-->>Breeze: 200 OK

Webhook Event

Listen to this webhook event:

{
  "type": "HEADLESS_KYC_STATUS_UPDATED",
  "signature": "<webhook_signature>",
  "data": {
    "id": "<headless_kyc_request_id>",
    "customerId": "<breeze_customer_id>",
    "accountId": "<breeze_account_id>",
    "kycId": "<breeze_kyc_id>",
    "kycStatus": "pending_user_info",
    "customerReferenceId": "<your_unique_user_id>",
    "tier": "TIER_3",
    "rejectionReason": null,
    "createdAt": 1710000000000,
    "updatedAt": 1710000001000
  }
}

Note the pending_user_info KYC status in the payload; this indicates a KYC tier 3 escalation was raised for this customer and it requires merchant action.

Handling Expired Persona Inquiries

In the event where the Persona inquiry link is expired before the user can complete it, you may refresh the inquiry by calling POST /v1/headless_kyc/:id/initiate_tier_3_kyc endpoint again with the same headless KYC request ID, and pass the new link to the customer.

API Documentation

• Initiate Tier 3 Headless KYC