KYC Webhook

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 offramp 100 USDC to customer
    Breeze-->>Merchant: Return hosted offramp page URL

    Note over Merchant, Customer: Step 2
    Merchant->>Customer: Redirect to Breeze hosted offramp 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	`Object`		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 abbrievation
address.postalCode	`string`	✅	Address postal code
address.country	`string`	✅	Address country of residence
phoneNumber	`string`	✅	Phone Number
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"
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
taxId	`string`	✅	Social security number

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"
  }
}