Quick Start

📘

Need a sandbox API key?

Just email us at [email protected] from your company email, and we’ll send you a test API key — no signup or onboarding required. You can start testing right away.

1. Create a Customer

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 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 '{
    "products": [
      {
        "name": "$10 Game Bundle",
        "currency": "USD",
        "amount": 1000,
        "images": ["https://storage.googleapis.com/breeze-sample-assets/icons/coin.png"],
        "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": {
      "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.

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

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