Send a request to create a payout page to transfer USDC $1 for testing. In this flow, you (the merchant) will also act as the customer. Use your own email address so you can receive the test payout page link.

1. Prerequisites

API key: Found in the Breeze Dashboard.
Base URL: https://api.breeze.cash
Tools: curl (or Postman / your HTTP client).
Webhook endpoint: Public HTTPS URL to receive events (configure in Dashboard).
Sandbox: to test your integration in sandbox environment, append query params of livemode=false

2. Create a Customer

Create a customer with Breeze by sending a request with the most basic parameters.

curl -X 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]",
    "signupAt": 1710000000000, // 2024-03-08T12:00:00.000Z, UTC+0 timestamp in milliseconds
  }'

Replace the placeholders:

<your-unique-user-id>: the unique user identifier in your system
[email protected]: use your email or an email you have access to

A succesful response will look like:

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

3. Create a Payout Page

With the customer created, send a request to create a payout page to transfer USD $1 to them

curl -X POST \
    'https://api.breeze.cash/v1/payout_pages?livemode=false' \
    -H 'content-type: application/json' \
    -H 'Authorization: Basic <Base64 encoded API key>' \
    --data-raw '{
      "amount": 100,
      "fundingCurrency": "USDC",
      "customer": {
          "referenceId": "<your-unique-user-id>",
          "email": "[email protected]"
      },
      "clientReferenceId": "<unique client reference ID>",
      "releaseMethod": "AUTOMATIC",
      "successReturnUrl": "<your-success-url>",
      "failureReturnUrl": "<your-failure-url>"
    }'

Replace the placeholders:

<Base64 encoded API key>: your Breeze API key, encoded in Base6
<unique client reference ID>: something unique such as a UUID~~
<your-success-url>: an optional field to pass a URL to which the user will be redirected after successfully completing the payout process
<your-failure-url>: an optional field to pass a URL to which the user will be redirected if they decide not to proceed with the payout

4. Redirect to the Payout Page

Once the payout page is created, you should receive a response with a unique url:

{
    "status": "SUCCEEDED",
    "data": {
        "id": "payout_page_562315443de70f4d",
        "status": "CREATED",
        "amount": 100,
        "fundingCurrency": "USDC",
        "clientReferenceId": "064143097e7640a798a4cc92742b1ba8",
        "releaseMethod": "AUTOMATIC",
        "merchant": {
            "id": "mch_mock_merchant",
            "livemode": false
        },
        "customer": {
            "id": "cus_123abc456", // The customer ID generated by Breeze
            "referenceId": "<your-unique-user-id>",
            "email": "[email protected]"
        },
        "url": "https://payout.qa.breeze.cash/payout-page/payout_page_562315443de70f4d"
    }
}

Open this URL in your browser (or redirect your customer in production).

5. Complete the customer flow

On the payout page, you will:

Choose the bank transfer payout method
Input the following mock bank account details:
1. Routing number: 011103093
2. Bank account number: 1111111
Confirm your payout details
Complete the KYC verification for the first time user with the following mock values:
1. SSN: 111-11-1111
2. Phone number: (555) 123-4567

6. Verify webhook events

You should receive multiple webhook events to your configured webhook url. You can observe the change in the status and sub-status fields as the payout page transitions from CREATED to PENDING to PROCESSING

7. Verify emails

You should receive emails at the address your provided informing of the progress of your payout.

8. Verify Payout Page Status

You can also fetch the current status via API

curl -X GET \
    'https://api.breeze.cash/v1/payout_pages/:payoutPageId?livemode=false' \
    -H 'Authorization: Basic <Base64 encoded API key>'

Replace the place holders:

:payoutPageId: ID of the payout page you want to retrieve
<base64 encoded API key>: your Breeze API key, encoded in Base64

which will return the following response

{
    "status": "SUCCEEDED",
    "data": {
        "id": "payout_page_562315443de70f4d",
        "status": "PROCESSED",
        "amount": 100,
        "fundingCurrency": "USDC",
        "clientReferenceId": "064143097e7640a798a4cc92742b1ba8",
        "releaseMethod": "AUTOMATIC",
        "merchant": {
            "id": "mch_mock_merchant",
            "livemode": false
        },
        "customer": {
            "id": "cus_123abc456", // The customer ID generated by Breeze
            "referenceId": "<your-unique-user-id>",
            "email": "[email protected]"
        },
        "url": "https://payout.qa.breeze.cash/payout-page/payout_page_562315443de70f4d",
        "customerConfirmedAt": 1756985660877
    }
}