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", then copy the key and use it as your API key in requests.

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

Non-required fields will be omitted from the response if they are null. See the API Reference tab for more details on request and response fields.

❌ 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

🌐 Sandbox vs. Production (livemode)

All API requests support a livemode flag that controls which environment you're targeting:

• livemode=false — targets the sandbox environment (test data, no real money movement). Append as a query parameter: ?livemode=false
• livemode=true (default) — targets production

Sandbox API keys (prefix sk_test_) only work with livemode=false. Production keys (prefix sk_live_) only work in production. Omitting livemode defaults to production.

🛡️ 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).