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 // 2024-03-08T12:00:00.000Z, UTC+0 timestamp in milliseconds
  }'

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: It has been changed to major unit format, which means currency: "USD" and amount: "100" means $100.
• image: Only one image is required, the images field has been deprecated.
• type: New field that is introduced that only takes in "REGULAR" (for non-Subscription products) or "SUBSCRIPTION" (for Subscription products)

We recommend a product image of size 500x500 of png image

It is recommended to create all product information in advance and re-use them 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>", // you only need to pass either id or referenceId
      "referenceId": "<your-unique-user-id>"
    }
  }'

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.