The Breeze JS SDK runs in the browser and provides a secure interface between your application and the Breeze platform. This includes Integration with risk assessment and more into your checkout experience.

Installation

Include the Breeze SDK by adding the following script tag to your HTML document. The SDK should be loaded before any initialization code executes. We recommend placing it in the <head> of your page or immediately before your closing </body> tag.

<script src="https://cdn.jsdelivr.net/gh/beamo-co/js@main/breeze.js"></script>

Important! Always load the SDK from the official CDN. Do not host the file yourself, as this may prevent you from receiving security patches and feature updates.

Initialization

After loading the SDK, create a new BreezeSdk instance by passing your configuration object. A publicKey is required for authentication and is provided by Breeze during merchant onboarding.

const breeze = new BreezeSdk({
  publicKey: 'YOUR_PUBLIC_KEY',
});

Risk Session

For Breeze Payin and Payout flows hosted on your own pages, you are required to integrate the Risk Session module. This module collects device fingerprint data and behavioral signals, which Breeze's risk engine uses to evaluate transaction risk in real time.

When a risk session is initialized, the SDK gathers device and environment metadata and returns a unique session identifier. You must include this identifier with every payment request sent to the Breeze API.

Full Example:

<!-- 1. Load the Breeze SDK -->
<script src="https://cdn.jsdelivr.net/gh/beamo-co/js@main/breeze.js"></script>

<script>
  // 2. Create a BreezeSdk instance
  const breeze = new BreezeSdk({
     publicKey: 'YOUR_PUBLIC_KEY',
  });

  // 3. Initialize the risk session on page load
  breeze.initSession();

  // 4. When the user submits a payment
  function handlePayment() {
    const session = breeze.getSession();

    // 5. Send the session ID to your backend
    fetch('/api/pay', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        amount: 1000,
        currency: 'USD',
        breezeSessionId: session.id,
      }),
    });
  }
</script>

Support

If you encounter integration issues, have feature requests, or need help with your Breeze SDK setup, reach out to the Breeze support team. We're here to help you get up and running.