Onboarding a Customer with KYC Data

This guide explains how to onboard a customer into Breeze by providing KYC data directly through the Customer Onboarding API. This approach allows your platform to reuse identity information you have already collected, minimizing the amount of KYC data your customers need to enter when they access Breeze’s payout services.

By sending KYC attributes during customer creation or update, Breeze can:

Perform KYC checks in the background without requiring additional input from the customer, if all required fields are provided.
Pre-fill the hosted verification form for cases where only partial information is available, reducing friction and improving completion rates.
Ensure a more seamless payout experience, especially for platforms that already maintain verified customer records.

This method is the recommended integration path for merchants who collect KYC information during their own onboarding flow and want to deliver a streamlined, low-friction experience to their users.

The sections below describe the required fields, request format, and how Breeze processes the data during KYC verification.

How It Works (Conceptual Overview)

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

Creating a Customer

To create a customer in Breeze, send a POST request to the Breeze API POST /v1/customers with the request payload detailed here.

curl --location --request POST 'https://api.breeze.cash/v1/customers' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "referenceId": "<your-unique-user-id>",
    "email": "[email protected]",
    "firstName": "John",
    "middleName": "K",
    "lastName": "Doe",
    "dateOfBirth": "1990-01-01",
    "address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    },
    "phoneNumber": "+14155552671",
    "signupAt": 1710000000000 // 2024-03-08T12:00:00.000Z, UTC+0 timestamp in milliseconds
  }'

Request payload

Fields	Type	Required	Description
referenceId	`string`	✅	Your system's reference ID for this user.
signupAt	`number`	✅	Epoch timestamp in milliseconds. Represents the timestamp when the customer signed up at your service. Passing this data to us helps with better risk management.
email	`string`		Email of the user
supportedPaymentMethods	`string[]`		Immutable field. Indicates the payment methods this customer can use. Once set, this field cannot be updated.
firstName	`string`		Max length 100
middleName	`string`		Max length 100
lastName	`string`		Max length 100
dateOfBirth	`string`		In `YYYY-MM-DD` format. Must be a past date, no more than 150 years ago.
phoneNumber	`string`		Max length 20. For United States, use either `XXXXXXXXXX`, `1XXXXXXXXXX` or `+1XXXXXXXXXX` format.
address	`Object`		See details on the nested fields in the rows below with prefix `address.`
address.line1	`string`		Sub-field of `address` object. Max length 255.
address.line2	`string`		Sub-field of `address` object. Max length 255.
address.city	`string`		Sub-field of `address` object. Max length 100.
address.state	`string`		Sub-field of `address` object. For United States, use either the Two-Letter State Abbreviations format or the ISO-3166-2 format.
address.postalCode	`string`		Sub-field of `address` object. For United States, use either the 5-digit format (`XXXXX`) or the ZIP+4 format (`XXXXX-YYYY`).
address.country	`string`		Sub-field of `address` object. In ISO 3166-1 alpha-2 format.

Response

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "cus_123abc456", // The customer ID generated by Breeze
    "referenceId": "<your-unique-user-id>",
    "email": "[email protected]"
    ...
  }
}

The data fields are as follows:

Fields	Type	Required	Description
id	`string`	✅	Breeze's generated ID for this user.
referenceId	`string`	✅	Your system's reference ID for this user.
signupAt	`number`	✅	Epoch timestamp in milliseconds. Represents the timestamp when the customer signed up at your service.
merchantId	`string`	✅	Breeze's merchant ID representing your business.
livemode	`boolean`	✅	Breeze's flag to indicate whether your merchant is in live mode or sandbox mode. `true` indicates live mode `false` indicates sandbox mode
email	`string`		Email of the user, only present if provided.
supportedPaymentMethods	`string[]`		Indicates the payment methods this customer can use, only present if provided.
supportedPayoutMethods	`string[]`		Indicates the payout methods this customer can use, only present if it has been set by admin.
firstName	`string`		Encrypted string containing the first name of the user, only present if provided.
middleName	`string`		Encrypted string containing the middle name of the user, only present if provided.
lastName	`string`		Encrypted string containing the last name of the user, only present if provided.
dateOfBirth	`string`		Encrypted string containing the date-of-birth of the user, only present if provided.
phoneNumber	`string`		Encrypted string containing the phone number of the user, only present if provided.
address	`Object`		See details on the nested fields in the rows below with prefix `address.`
address.line1	`string`		Encrypted string containing the first line of the user's address, only present if provided.
address.line2	`string`		Encrypted string containing the second line of the user's address, only present if provided.
address.city	`string`		Encrypted string containing the city of the user's address, only present if provided.
address.state	`string`		Encrypted string containing the state of the user's address, only present if provided.
address.postalCode	`string`		Encrypted string containing the postal code of the user's address, only present if provided.
address.country	`string`		Encrypted string containing the country of the user's address, only present if provided.

Updating a Customer

To update a customer in Breeze, send a POST request to the Breeze API POST /v1/customers/:customerId with the request payload detailed here.

These are the fields that we support updates for:

Address
Email

curl --location --request POST 'https://api.breeze.cash/v1/customers/cus_172e1e324a25e95a' \
  --header 'Authorization: Basic <your token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email": "<updated value>",
    "address": {
      "line1": "<updated value>",
      "line2": "<updated value>",
      "city": "<updated value>",
      "state": "<updated value>",
      "postalCode": "<updated value>",
      "country": "<updated value>"
    }
  }'

Request payload

Fields	Type	Description
email	`string`	Email of the user
address	`Object`	See details on the nested fields in the rows below with prefix `address.`
address.line1	`string`	Sub-field of `address` object. Max length 255.
address.line2	`string`	Sub-field of `address` object. Max length 255.
address.city	`string`	Sub-field of `address` object. Max length 100.
address.state	`string`	Sub-field of `address` object. For United States, use either the Two-Letter State Abbreviations format or the ISO-3166-2 format.
address.postalCode	`string`	Sub-field of `address` object. For United States, use either the 5-digit format (`XXXXX`) or the ZIP+4 format (`XXXXX-YYYY`).
address.country	`string`	Sub-field of `address` object. In ISO 3166-1 alpha-2 format.

Response

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "cus_123abc456", // The customer ID generated by Breeze
    "referenceId": "<your-unique-user-id>",
    "email": "[email protected]"
    ...
  }
}

The data fields are as follows:

Fields	Type	Required	Description
id	`string`	✅	Breeze's generated ID for this user.
referenceId	`string`	✅	Your system's reference ID for this user.
signupAt	`number`	✅	Epoch timestamp in milliseconds. Represents the timestamp when the customer signed up at your service.
merchantId	`string`	✅	Breeze's merchant ID representing your business.
livemode	`boolean`	✅	Breeze's flag to indicate whether your merchant is in live mode or sandbox mode. `true` indicates live mode `false` indicates sandbox mode
email	`string`		Email of the user, only present if provided.
supportedPaymentMethods	`string[]`		Indicates the payment methods this customer can use, only present if provided.
supportedPayoutMethods	`string[]`		Indicates the payout methods this customer can use, only present if it has been set by admin.
firstName	`string`		Encrypted string containing the first name of the user, only present if provided.
middleName	`string`		Encrypted string containing the middle name of the user, only present if provided.
lastName	`string`		Encrypted string containing the last name of the user, only present if provided.
dateOfBirth	`string`		Encrypted string containing the date-of-birth of the user, only present if provided.
phoneNumber	`string`		Encrypted string containing the phone number of the user, only present if provided.
address	`Object`		See details on the nested fields in the rows below with prefix `address.`
address.line1	`string`		Encrypted string containing the first line of the user's address, only present if provided.
address.line2	`string`		Encrypted string containing the second line of the user's address, only present if provided.
address.city	`string`		Encrypted string containing the city of the user's address, only present if provided.
address.state	`string`		Encrypted string containing the state of the user's address, only present if provided.
address.postalCode	`string`		Encrypted string containing the postal code of the user's address, only present if provided.
address.country	`string`		Encrypted string containing the country of the user's address, only present if provided.