API Fundamentals

Before diving into the endpoints, here’s how to authenticate your API request and what you can expect across all Breeze API responses — so you can handle success, failure, and edge cases consistently.

🔒 Authentication

We're using HTTP authentication to authenticate your API requests. Before you get started, you'll need to obtain an API Key, which will be used as the username, while the password is always an empty string.

await axios.get("https://api.breeze.cash/v1/api/...", {
  auth: {
    username: "your-breeze-api-key",
    password: "", // <- always empty
  },
});

✅ Success Response

Successful API requests will return an HTTP 200 status and a JSON body with a status of SUCCEEDED, along with a data object containing the result.

{
  "status": "SUCCEEDED",
  "data": {
    "id": "page_abc123xyz",
    ...
  }
}

• status: Will always be SUCCEEDED
• data: Contains the actual result object (e.g., payment page info, payment status, etc.)

❌ Error Response

Failed requests will return a non-2xx HTTP status code (typically 400 or 500) with an error object like:

{  
  "status": "FAILED",  
  "errorCode": "INVALID_REQUEST",
  "errorMessage": "The 'amount' field is required."
}

• status: Will always be FAILED
• errorCode: Machine-readable error type
• errorMessage: Human-friendly explanation

🚦 Status Codes

🛡️ Idempotency & Retry Safety

• Creating a payment page is idempotent per clientReferenceId. If you accidentally resend the same request, you’ll receive the same payment page.
• Webhooks may occasionally be retried — your webhook handler should be idempotent (e.g., check if the order is already marked as paid before updating again).