📘 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.

Breeze uses Persona as its identity verification provider. Persona handles document checks, biometric verification, and sanctions screening on Breeze's behalf.

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.

1. 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: Option 1: Providing KYC Data via Customer Onboarding API (Recommended).

2. If Breeze has no KYC data for the customer, but the merchant can supply it

   There are two subcases depending on when and how you want KYC to happen:

   • The merchant wants to onboard users before they ever initiate a payout — Submit the customer's KYC data directly to Breeze via API, outside of any payout flow. Your platform is responsible for obtaining user consent and presenting Breeze and Breeze's partner's T&Cs before submission.

     See: Option 3: Headless KYC.

   • The merchant wants Breeze to handle onboarding during the payout flow — Breeze requests KYC data from your backend via the KYC_DATA_REQUIRED webhook when a payout is initiated. Breeze surfaces its own T&Cs to the user and collects their acceptance on the hosted payout page.

     See: Option 2: Using Breeze Webhooks.

3. 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

📘

The fields required to satisfy KYC requirements can be found in KYC Tiers & Fields.

Option 1: 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

⚠️

Important: taxId (SSN) cannot be submitted via the Customer Onboarding API.

Even when using Option 1, the taxId field (required for all KYC tiers) must be entered by the end-user directly through the hosted KYC form. This means Option 1 alone will always result in a partially pre-filled form — it cannot fully bypass the KYC UI. If you need to skip the hosted form entirely, use Option 2: KYC Webhook or Option 3: Headless KYC.

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 KYC data (note: taxId always collected from user separately)
        Breeze->>Customer: Show hosted Persona KYC widget prefilled with merchant-supplied data
        Customer->>Persona: User enters taxId and reviews prefilled fields
        Persona-->>Breeze: KYC validation result
    else No KYC data provided by merchant
        Breeze->>Customer: Show blank hosted Persona KYC widget
        Customer->>Persona: User enters all fields manually
        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 Option 1: Onboarding a Customer with KYC Data

Option 2: 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:

1. When a user initiates a payout transaction on Breeze, we send a webhook notification with type KYC_DATA_REQUIRED to your configured endpoint.
2. Your system responds with the user's KYC attributes according to the required schema.
3. 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 Option 2: KYC Webhook

Option 3: Headless KYC

🚧

This option is only available to merchants configured by the Breeze team. Please reach out to Breeze to find out more.

For merchants who run their own KYC process end-to-end, Headless KYC allows you to submit the complete KYC payload — including identity document images — directly to Breeze via API.

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
• Requires you to handle surfacing Breeze's & Breeze's partner's T&Cs
• Allows users to be onboarded before even doing any payout, which could speed up the payout flow the most

📘

See more details on implementation in Option 3: Headless KYC.

📋 Things to Note

KYC Requirements by Payout Method

Breeze uses a tiered KYC model — the minimum tier required depends on the payout method the end-user selects. For example, crypto payouts require a higher tier than card or bank transfers.

For a full breakdown of what each tier collects and when each tier is required, see KYC Tiers & Fields.

Diagnosing KYC-related Payout Statuses

If a payout returns "pendingStatus": "PENDING_USER_ONBOARDING", this typically means the associated customer has not yet completed the KYC tier required for that payout method. Check which payout method is being used and refer to the tier requirements above to confirm what the user still needs to complete.

See also: Payout Page Statuses and Sub-Statuses

KYC Rejection

If a customer's KYC is rejected, they will be blocked from completing payouts. This applies regardless of the payout method — a user rejected during a crypto payout attempt will also be unable to complete a FIAT payout.

KYC rejections can occur for a variety of reasons. For merchants who supply customer data via the Customer Onboarding API, one example is a USER_NAME_MISMATCH error, which may indicate a discrepancy between the name supplied in the Customer API record and the name submitted during the KYC process. In cases like this, checking whether the data passed to Breeze aligns with what the user provided during KYC is a good starting point for diagnosis.

📘

If you believe a rejection occurred due to a data issue on your end, please reach out to Breeze support with the Customer ID and payout details for further investigation.