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:

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": "10",
        "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-<your-unique-id>",
    "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 major units (e.g., `"10"` = USD 10.00)
`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

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "page_abc123xyz",
    "url": "https://pay.breeze.cash/page_abc123xyz/pcs_xxx",
    ...
  }
}

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.

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 Products 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-<your-unique-id>",
    ...
  },
  "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 production credentials if applicable.