API Fundamentals

📘

To kickstart your integration with Breeze, please contact us here

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 use Basic Authentication to authenticate API requests. Before you get started, you’ll need to obtain an API key, which is 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
  },
});

import requests

response = requests.get(
    "https://api.breeze.cash/v1/api/...",
    auth=("your-breeze-api-key", "")
)

<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://api.breeze.cash/v1/api/...");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "your-breeze-api-key:");

$response = curl_exec($ch);
curl_close($ch);
?>

import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class BreezeAPI {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://api.breeze.cash/v1/api/...");
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            String auth = "your-breeze-api-key:";
            String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes());
            connection.setRequestProperty("Authorization", "Basic " + encodedAuth);

            int responseCode = connection.getResponseCode();
            // Handle the response
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

You may obtain the sandbox environment API key from the sandbox merchant dashboard. Under the Developers section, click on "Generate new API Key" and follow the instructions displayed on the dashboard.

Note:

Sandbox API keys have the prefix sk_test_, while production API keys have the prefix sk_live_.

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