Quick Start

Accept a payment in a few steps — no need to pre-create products.

1. Create a Customer

Create the customer before creating the payment page, then reference them in Step 2. This lets you reuse the customer across multiple payment pages.

Create a customer with Breeze by sending a request with the most basic parameters. See Customer Overview for more details.

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]: the customer's email address

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,
    ...
  }
}

2. Create a Payment Page

Send a POST request to create a payment page with the customer and inline product details. For quick testing, use cURL. See 📄 API Reference — Create a payment page for the full request/response schema.

curl -X POST 'https://api.breeze.cash/v1/payment_pages' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "lineItems": [
      {
        "clientProductId": "game-bundle-001",
        "displayName": "$10 Game Bundle",
        "amount": 1000,
        "currency": "USD",
        "image": "https://storage.googleapis.com/breeze-sample-assets/icons/coin.png",
        "description": "A bundle of 10 in-game coins",
        "quantity": 1
      }
    ],
    "customer": {
      "referenceId": "<your-unique-user-id>",
      "email": "[email protected]",
      "signupAt": 1710000000000
    },
    "clientReferenceId": "order-001",
    "successReturnUrl": "https://your-domain.com/order-complete",
    "failReturnUrl": "https://your-domain.com/order-aborted"
  }'

Customer fields:

The customer object supports three modes — provide exactly one:

Inline product fields:

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "page_abc123xyz",
    "url": "https://pay.breeze.cash/page_abc123xyz/pcs_xxx",
    "expireAtSeconds": 604800,
    "customer": {
      "id": "cus_123abc456", // The customer ID generated by Breeze
      "referenceId": "<your-unique-user-id>",
      ...
    },
    "lineItems": [
      {
        "productId": "prd_abc123xyz",  // auto-assigned by Breeze
        ...
      }
    ],
    ...
  }
}

• data.id — A unique identifier for tracking this transaction on Breeze's side.
• data.url — The URL you redirect your customer to for completing the payment.
• data.expireAtSeconds — How long the payment page remains open, in seconds from creation. Default is 604800 (7 days). The response contains additional fields beyond those shown here — see the API Reference for the full schema.
• data.customer.id — The Breeze customer ID linked to this payment page. Store it to reference the customer directly in future requests.
• data.lineItems[].productId — Auto-assigned by Breeze for each inline line item. This is the internal product ID created or reused for the clientProductId you provided.
• data.lineItems[].images — Note that the request uses image (singular string) but the response returns images (array of strings). This is an intentional transformation.

{
  "lineItems": [{ "product": "prd_123abc456", "quantity": 1 }],
  "customer": { "id": "cus_123abc456" }
}

3. Redirect the User

Once you have the data.url, redirect the user's browser to that URL. The user will see Breeze's hosted payment page, where they can choose their payment method (card, crypto, etc.) and complete the transaction.

4. Handle Webhooks

After the payment succeeds or fails, Breeze will send a webhook notification to your server or application. Here’s a minimal example of what that webhook payload might look like:

{
  "type":"PAYMENT_SUCCEEDED",
  "data":{
    "pageId":"page_abc123xyz",
    "status":"PAID",
    "clientReferenceId":"order-001",
    ...
  },
  "signature":"<webhook-payload-signature>"
}

• At a high level, you’ll need an endpoint (e.g., /webhook) in your server or application that can accept this JSON payload via a POST request.
• When you receive it, update your internal records to mark the payment as successful (or failed, if status indicates otherwise).

Next Steps

• Secure Your Webhook: Validate that incoming webhook requests come from Breeze (e.g., signature checks) before processing.
• Add Customization: Include additional parameters (like return urls, expiry time, or custom fields) to tailor the payment page.
• Pre-create Products: For production use, create products upfront and reference them by ID for optimal performance.
• Go Live: Once you've tested successfully in your environment, swap to your production credentials when ready to go live.

Error codes — For a complete list of errors that can be returned during payment page creation, see the Error Reference.