Option 2: KYC Webhook

🚧
Note: This feature is only available to merchants configured by the Breeze team. Please reach out to the Breeze team to find out more.

Our platform streamlines KYC verification by enabling merchants to securely share existing customer KYC data, eliminating duplicate verification processes for users accessing our Payout services. This integration ensures efficient onboarding while maintaining robust compliance standards.

When a user initiates a Payout transaction on our platform, we send a webhook notification with type KYC_DATA_REQUIRED to the configured endpoint. Upon receiving the required KYC data in response, we onboard the user to our KYC provider (Persona) to verify their identity and compliance status.

How It Works (Conceptual Overview)

sequenceDiagram
    participant Merchant
    participant Customer
    participant Breeze
    participant Persona
    participant MerchantWebhook as "Merchant Webhook"

    Note over Merchant: Step 1
    Merchant->>Breeze: Request to payout 100 USDC to customer
    Breeze-->>Merchant: Return hosted payout page URL

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

    Note over Customer, Breeze: Step 3
    Customer->>Breeze: Open hosted page and start KYC process

    Note over Breeze: Step 4 – Branch
    alt Merchant has NO KYC info
        Breeze->>Customer: Display Persona-hosted KYC UI
        Customer->>Persona: Submit KYC info
        Persona-->>Breeze: KYC validation result
    else Merchant has KYC info
        Breeze->>MerchantWebhook: Request customer KYC info
        MerchantWebhook-->>Breeze: Return customer KYC info
        Breeze->>Persona: Submit KYC info via API
        Persona-->>Breeze: KYC validation result
    end

    Note over Breeze: Step 5
    Breeze-->>Breeze: Wait until KYC is approved
    Breeze->>Breeze: Proceed to money movement

Webhook payload

Fields	Type	Description
type	`string`	Webhook Type: `KYC_DATA_REQUIRED`
signature	`string`	Webhook signature for verification
data	`Object`	Webhook data
data.email	`string`	Email of KYC user

Example Webhook Payload:

{
  "type": "KYC_DATA_REQUIRED",
  "signature": "example_webhook_signature",
  "data": {
    "email": "[email protected]"
  }
}

Expected webhook response

Fields	Type	Required	Description	Notes
email	`string`	✅	Email of KYC user
kycStatus	`pending`\|`approved`\| `rejected`	✅	KYC status	We will only process data for `approved`
firstName	`string`	✅	First Name
middleName	`string`		Middle Name (optional)
lastName	`string`	✅	Last Name
dateOfBirth	`string`	✅	Date of birth	`YYYY-MM-DD`
country	`string`	✅	Country of residence
address	`object`	✅	Address components
address.line1	`string`	✅	Address line 1
address.line2	`string`		Address line 2 (optional)
address.city	`string`	✅	Address city
address.state	`string`	✅	Address state abbreviation
address.postalCode	`string`	✅	Address postal code
address.country	`string`	✅	Address country of residence
phoneNumber	`string`	✅	Phone Number
taxId	`string`	✅	Tax identification number (e.g. SSN for US customers)
document	`object`	✅	Document components
document.type	`string`	✅	Document Type	Drivers License = "dl" Identification Card = "id" Passport = "pp" Passport Card = "ppc" Permanent Residence Card = "pr" Work Permit = "wp" Note: Option 2 uses short-code values (e.g. "dl", "pp"). Option 3 (Headless KYC) uses a different format — see Option 3 document types.
document.frontImageUrl	`string`	✅	Front Image url
document.backImageUrl	`string`	✅	Back Image url	Optional for passport (”pp”)
document.documentNumber	`string`	✅	Document number of the document	For example, document number would be the passport number for passport document

Note

Recommended document types:

Drivers License = "dl"

Identification Card = "id"

Passport = "pp"

Passport Card = "ppc"

Permanent Residence Card = "pr"

Work Permit = "wp"

Other supported document types:

Certificate of Citizenship = "cct"

Consular Id = "cid"

Immigration Visa = "visa"

Residence Permit = "rp"

Municipal Id = "munid"

Australia Keypass Id = "keyp"

Canada Health Insurance Card = "hic"

Colombia Foreigner Id = "foid"

India Permanent Account Number Card = "pan"

Japan MyNumber Card = "myn"

Philippines National Bureau of Investigation Certificate = "nbi"

Philippines Social Security System Card = "sss"

Philippines Unified Multi Purpose Id = "umid"

Philippines Overseas Foreign Worker Card = "ofw"

Philippines Postal Identification Card = "pid"

Russia Internal Passport = "ipp"

Singapore Long Term Visit Pass = "ltpass"

Singapore National Residency Id = "nric"

Us Refugee Travel Document = "td"

Example expected webhook response:

{
  "email": "[email protected]",
  "kycStatus": "approved",
  "firstName": "John",
  "middleName": "K",
  "lastName": "Doe",
  "dateOfBirth": "1990-01-01",
  "country": "US",
  "address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "phoneNumber": "+14155552671",
  "taxId": "123-45-6789",
  "document": {
    "type": "pp",
    "frontImageUrl": "https://merchant-cdn.com/docs/john-passport-front.jpg",
    "backImageUrl": "https://merchant-cdn.com/docs/john-passport-back.jpg",
    "documentNumber" : "123456789"
  }
}