Guides

Quick Start: Create and Test a Payout Page

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 (Optional)

You can either pre-create a customer and reference them by ID, or pass customer details inline when creating the payout page in Step 3. Pre-creating is recommended for production — it lets you reuse the customer across multiple payout pages.

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 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]",
    "signupAt": 1710000000000,
    ...
  }
}

3. Create a Payout Page

With the customer created, send a request to create a payout page to transfer USDC $1 to them. See 📄 API Reference — Create a payout page.

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

Replace the placeholders:

  • your-unique-ref-id: a unique identifier for this payout in your system. Must contain only alphanumeric characters and hyphens — no spaces or special characters like <, >. Example: payout-7f3a8b2c or a UUID string.
  • <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

Note: Both successReturnUrl and failureReturnUrl must include the full URL with protocol (e.g. https://your-domain.com/success). URLs without https:// are silently accepted but the redirect will fail at checkout.

For initial sandbox testing, you may use AUTOMATIC release method to simplify the first test. But our recommendation is to use MANUAL release method so that you have more control on the confirmation for the fund release. The details on manual release can be found in the Payout Release Flow guide

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

  1. Choose the bank transfer payout method
  2. Input the following mock bank account details:
    1. Routing number: 011103093
    2. Bank account number: 1111111
  3. Confirm your payout details
  4. 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

If you wish to test a customer flow with crypto:

  1. Generate a test crypto wallet address via https://vanity-eth.tk/ if you don't already have one.
  2. Input any wallet address on the payment page.
📘

You won't be able to verify the money crediting to the wallet as there is no actual money movement in sandbox.

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/payout_page_abc123xyz?livemode=false' \
    -u "YOUR_API_KEY:"

Replace the placeholders:

  • payout_page_abc123xyz: replace with the payout page id from Step 3's response

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.breeze.cash/payout-page/payout_page_562315443de70f4d",
        "customerConfirmedAt": 1756985660877
    }
}

Error codes — For a complete list of errors returned by the payout page endpoints, see the Error Reference.

Webhooks — For payload examples and event sequences fired during payout flows (PAYOUT_PAGE_STATUS_UPDATE, PAYOUT_PAGE_PENDING_STATUS_UPDATE), see the Webhook Event Reference.

Updated 7 days ago