Quick Start

1. Create a Customer (If you haven't)

Send a POST request to the Breeze API with the most basic parameters. For quick testing, you can use a command-line tool like cURL:

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
  }'

Note

• referenceId and email must be unique.
• signupAt is required and must be a UTC timestamp (ms).
• This API uses Basic Authentication. When using curl, make sure to include a trailing colon ":" after your API key. Omitting the colon will cause authentication to fail.

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 Product (If you haven't)

curl -X POST 'https://api.breeze.cash/v2/products' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "displayName": "$10 Game Bundle",
    "currency": "USD",
    "amount": "100",
    "description": "Description for the product",
    "image": "https://storage.googleapis.com/breeze-sample-assets/icons/coin.png",
    "type": "REGULAR"
  }'

❗️

For users who migrated from product API v1

• amount: Now uses major units. For example, currency: "USD" and amount: "100" represents USD 100.
• image: Only one image is required. The images field has been deprecated.
• type: New required field. Must be either "REGULAR" (for non-subscription products) or "SUBSCRIPTION" (for Subscription products)

Note

• We recommend a 500×500 PNG product image.
• It is recommended to create all product information in advance and reuse it in subsequent Create Payment Page requests for optimal performance.

3. Create a Payment Page

With the customer created, you can create a payment page by sending a POST request to the Breeze API.

curl -X POST 'https://api.breeze.cash/v1/payment_pages' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "lineItems": [
      {
        "product": "<your-product-id>",
        "quantity": 1
      }
    ],
    "billingEmail": "[email protected]",
    "clientReferenceId": "order-<your-unique-id>",
    "successReturnUrl": "https://your-domain.com/order-complete",
    "failReturnUrl": "https://your-domain.com/order-aborted",
    "customer": {
      "id": "<breeze-customer-id>",
      "referenceId": "<your-unique-user-id>"
    }
  }'

Note

• <your-product-id> is the product ID returned in step 2 prd_xxxx
• For the customer field, you can pass either the id or the referenceId.

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’ll redirect your customer to for completing the payment.

4. Redirect the User

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

5. 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.
• Go Live: Once you’ve tested successfully in your environment, swap to production credentials if applicable.