📘 Overview: Why KYC Is Needed

Know Your Customer (KYC) is a regulatory requirement designed to verify the identity of individuals and businesses involved in financial transactions. Breeze implements KYC to ensure compliance with financial regulations, prevent fraud, and maintain a secure ecosystem for all customers and partners.

📘
KYC is a mandatory step of the Payout process. For more information on how payouts work, refer to: Payout (Payout Page)

🔗 How KYC Integrates With Breeze

Breeze provides multiple integration paths depending on your onboarding flow, customer experience requirements, and how much KYC data your platform already collects.

High-Level Overview

The diagram below shows the high-level flow of how KYC is handled as part of Breeze’s payout process, regardless of which integration method you choose.

sequenceDiagram
    participant Merchant
    participant Customer
    participant Breeze
    participant Persona

    Note over Merchant: Step 1 – Customer setup
    Merchant->>Breeze: Create customer (optionally with KYC info)
    Breeze-->>Merchant: Return Breeze customer ID

    Note over Merchant: Step 2 – Payout initiation
    Merchant->>Breeze: Request payout
    Breeze-->>Merchant: Return hosted payout page URL

    Note over Merchant, Customer: Step 3 – Redirect
    Merchant->>Customer: Redirect to Breeze hosted payout page

    Note over Customer, Breeze: Step 4 – Start KYC
    Customer->>Breeze: Open hosted page / start KYC process

    Note over Breeze, Persona: Step 5 – KYC verification
    Breeze->>Persona: Provide KYC data (backend or via Persona UI)
    Persona-->>Breeze: KYC validation result

    Note over Breeze: Step 6 – Money movement
    Breeze-->>Breeze: Proceed with payout after KYC is approved

How Breeze Chooses a KYC Path

For a new customer going through KYC for the first time, Breeze determines the verification path based on the KYC information available from the merchant and from the customer’s input.

If Breeze has partial KYC data for the customer

→ We prefill the Persona KYC form with the information you supplied (typically through the Customer Onboarding API). The customer will only be asked to review and fill in any missing details.

This approach:
- Reduces friction significantly
- Ensures users only provide information you don’t already have
- Offers the smoothest onboarding experience
See: Providing KYC Data via Customer Onboarding API (Recommended).
If Breeze has no KYC data for the customer, but the merchant can supply it

→ Breeze requests KYC information from your backend through the KYC_DATA_REQUIRED webhook, and uses that data to verify the customer directly via API.

If you provide the complete KYC payload:
- The customer may skip the Persona UI entirely
- Verification is fully backend-driven
See: Using Breeze Webhooks.
If neither Breeze nor the merchant has KYC data

→ Breeze presents the full Persona-hosted KYC UI for the customer to complete all required fields.

This follows the same flow as Client-Driven KYC (UI-based).

1. Client-Driven KYC (UI-based)

You can direct your customers to Breeze’s Payout Page, which includes a hosted KYC widget. Users will enter and submit all required KYC information directly through Breeze.

This approach:

Requires minimal engineering effort
Handles document collection and verification end-to-end
Minimizes the need to manage sensitive identity information on your side

2. API-Driven KYC

This option is ideal for merchants who already collect and store compliant KYC information and are able to securely share it with Breeze.

This approach:

Eliminates duplicate verification steps for customers accessing Breeze’s payout services
Requires explicit user consent to share their existing KYC data
Allows you to control the overall customer onboarding experience

Providing KYC Data via Customer Onboarding API (Recommended)

You may supply required KYC information directly through Breeze’s Customer Onboarding API. Any data provided will be used to prefill the verification form before it is presented to customers.

This approach:

Enables full backend-driven identity collection
Works well when your platform already maintains verified customer profiles
Reduces user friction — customers will only be asked to fill in missing fields

sequenceDiagram
    participant Merchant
    participant Breeze
    participant Persona
    participant Customer

    Note over Merchant: Step 1 – Create Customer with KYC attributes
    Merchant->>Breeze: Create Customer via Onboarding API<br/>(includes merchant-collected Customer KYC data)
    Breeze-->>Merchant: Return Breeze Customer ID

    Note over Merchant: Step 2 – Payout initiation
    Merchant->>Breeze: Request payout for the Customer
    Breeze-->>Merchant: Return hosted payout page URL

    Note over Customer, Breeze: Step 3 – Customer opens payout page
    Merchant->>Customer: Redirect to hosted payout page
    Customer->>Breeze: Open payout page / begin KYC step

    Note over Breeze: Step 4 – Evaluate Customer KYC data from Merchant
    alt Merchant provided sufficient Customer KYC data
        Breeze->>Persona: Submit Customer's KYC data via API
        Persona-->>Breeze: KYC validation result
    else Merchant provided partial or incomplete Customer KYC data
        Breeze->>Customer: Show hosted Persona KYC widget<br/>prefilled with Customer data from Onboarding API
        Customer->>Persona: Provide remaining KYC details
        Persona-->>Breeze: KYC validation result
    end

    Note over Breeze: Step 5 – Money movement
    Breeze-->>Breeze: Proceed to payout once KYC is approved

📘
See more details on implementation in Onboarding a Customer with KYC Data

Using Breeze Webhooks

Alternatively, you may provide required KYC information by responding to Breeze’s KYC_DATA_REQUIRED webhook.

The overall flow is as follows:

When a user initiates a payout transaction on Breeze, we send a webhook notification with type KYC_DATA_REQUIRED to your configured endpoint.
Your system responds with the user’s KYC attributes according to the required schema.
Breeze then uses this information to onboard the user to our KYC provider (Persona) for verification.

This option:

Enables backend-driven identity collection
Integrates cleanly into systems that already maintain customer identity records
If the full set of required fields is provided, users will not need to enter any additional KYC data

sequenceDiagram
    participant Merchant
    participant Webhook
    participant Breeze
    participant Persona

    Note over Merchant, Breeze: Step 1 – Payout for customer without KYC in Breeze
    Merchant->>Breeze: Request payout for customer
    Breeze-->>Merchant: Return hosted payout page URL

    Note over Breeze, Webhook: Step 2 – Request additional KYC
    Breeze->>Webhook: Webhook `KYC_DATA_REQUIRED`
    Webhook-->>Breeze: Respond with customer KYC data

    Note over Breeze, Persona: Step 3 – Verification
    Breeze->>Persona: Submit KYC data via API
    Persona-->>Breeze: KYC validation result

    Note over Breeze: Step 4 – Money movement
    Breeze-->>Breeze: Proceed to payout if KYC is approved

📘
See more details on implementation in KYC Webhook