Quick Start

Accept a payment in 3 steps — no need to pre-create customers or products.

1. Create a Payment Page

Send a POST request to create a payment page with 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
      }
    ],
    "billingEmail": "[email protected]",
    "clientReferenceId": "order-001",
    "successReturnUrl": "https://your-domain.com/order-complete",
    "failReturnUrl": "https://your-domain.com/order-aborted"
  }'

📘
This API uses Basic Authentication. When using curl, include a trailing colon ":" after your API key (-u "YOUR_API_KEY:"). Omitting the colon will cause authentication to fail.

Inline product fields:

Field	Description
`clientProductId`	Your unique identifier for this product
`displayName`	Product name shown to the customer on the payment page
`amount`	Price in minor units (cents). e.g. `1000` = USD 10.00, minimum `100`
`currency`	Three-letter currency code (e.g., `"USD"`)
`image`	URL to a product image (recommended: 500×500 PNG)
`description`	Short description of the product
`quantity`	Number of units the customer is purchasing
`clientReferenceId`	Your unique identifier for this payment in your system (e.g. `order-001`). Must contain only alphanumeric characters and hyphens — no spaces or special characters.

⚠️
Each time you create a payment page with an inline clientProductId and a new amount, Breeze silently creates a new price on that product server-side. Repeatedly calling with the same clientProductId but different amounts causes the product to accumulate multiple active prices. For production use, pre-create products and prices and reference them by ID to avoid this.

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "page_abc123xyz",
    "url": "https://pay.breeze.cash/page_abc123xyz/pcs_xxx",
    "expireAtSeconds": 604800,
    "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.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.

Optional: Pre-create Customers and Products for reuse

For production integrations where you process many payments, you can pre-create Customers and Products via their dedicated APIs, then reference them by ID in the payment page request. This avoids sending product details on every call and lets you manage products centrally.

Create a Customer: POST /v1/customers — See Customer Overview guide
Create a Product: POST /v2/products — See Products guide

Then reference them in your payment page request:

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

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

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