Embed Chargebee Checkout in Your Website

Embedded checkout keeps customers on your website while they complete a secure, Chargebee-hosted checkout. Chargebee.js creates and manages the checkout iframe, so sensitive payment details never reach your servers.

Embedded checkout is supported only with the full-page checkout layout. Enable and configure that layout before you begin.

Prerequisites

Sign up for a Chargebee account.
Ensure the full-page checkout layout is enabled for your site.
Create an item price on your Chargebee test site.
Get a publishable API key for your test site.
Decide how you will start checkout: with a Chargebee.js cart, a hosted page created by your server, or a payment link.

Add the checkout container

Load Chargebee.js and add an element where checkout should appear. Give the container enough width for the checkout form; its height will be updated after checkout loads.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Honey Comics | Pricing</title>
    <script src="https://js.chargebee.com/v2/chargebee.js"></script>
  </head>
  <body>
    <main>
      <h1>Complete your subscription</h1>
      <div id="checkout"></div>
    </main>
    <script src="/checkout.js"></script>
  </body>
</html>

Initialize Chargebee.js

Initialize Chargebee.js with your site name and publishable API key. A publishable key is designed for client-side code; never put a full-access API key in the browser.

const chargebee = Chargebee.init({
  site: "your-chargebee-subdomain",
  publishableKey: "your-chargebee-publishable-api-key",
});

Create and mount checkout

Pass either a cart or a hosted checkout url to createCheckout(). The method returns a checkout object; call mount() on that object to render checkout in the container.

Choose the option that matches your integration.

Use a cart when you build the selected product with Chargebee.js. Set the product layout to full_page before adding it to the cart.

async function mountCartCheckout() {
  const cbInstance = chargebee.getInstance();
  const cart = cbInstance.getCart();

  cart.setCustomer({
    first_name: "John",
    last_name: "Smith",
    email: "john@example.com",
    billing_address: {
      first_name: "John",
      last_name: "Smith",
      line1: "132 My Street",
      city: "Kingston",
      state_code: "NY",
      country: "US",
      zip: "12401",
    },
  });

  const product = cbInstance.initializeProduct(
    "cbdemo_advanced-USD-monthly",
    1
  );
  product.isItemsModel = true;
  product.setLayout("full_page");
  cart.replaceProduct(product);

  const checkout = await cbInstance.createCheckout({
    cart,
    callbacks: checkoutCallbacks,
  });

  checkout.mount("#checkout");
}

mountCartCheckout().catch(handleCheckoutError);

Use the Hosted Pages API when your server creates a checkout for each session. Your endpoint must make the authenticated Chargebee API call on the server and return the hosted page URL to the browser.

async function mountHostedPageCheckout() {
  const response = await fetch("/api/create-checkout", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      item_price_id: "cbdemo_advanced-USD-monthly",
    }),
  });

  if (!response.ok) {
    throw new Error("Could not create the hosted page");
  }

  const { url } = await response.json();
  const checkout = await chargebee.getInstance().createCheckout({
    url,
    callbacks: checkoutCallbacks,
  });

  checkout.mount("#checkout");
}

mountHostedPageCheckout().catch(handleCheckoutError);

Keep your full-access API key on the server. The browser should receive only the hosted page URL from your endpoint.

Use a payment link when the same checkout configuration can be reused. Generate the link from Integrate with Chargebee in the Chargebee app, then pass it as the url.

async function mountPaymentLinkCheckout() {
  const paymentLink =
    "https://your-chargebee-subdomain.chargebee.com/hosted_pages/checkout?...";

  const checkout = await chargebee.getInstance().createCheckout({
    url: paymentLink,
    callbacks: checkoutCallbacks,
  });

  checkout.mount("#checkout");
}

mountPaymentLinkCheckout().catch(handleCheckoutError);

Handle checkout events and resizing

Define the callbacks used above before calling your mount function. The resize callback keeps the container the same height as the hosted checkout while the customer moves between steps.

const checkoutContainer = document.querySelector("#checkout");

const checkoutCallbacks = {
  loaded: () => {
    console.log("Checkout loaded");
  },
  success: (data) => {
    console.log("Checkout completed. Hosted page ID:", data.id);
  },
  close: () => {
    console.log("Checkout closed");
  },
  step: (value) => {
    console.log("Checkout step:", value);
  },
  resize: (height) => {
    checkoutContainer.style.height = `${height}px`;
  },
  error: (error) => {
    handleCheckoutError(error);
  },
};

function handleCheckoutError(error) {
  console.error("Checkout failed:", error);
}

Use the hosted page ID received by success to retrieve the hosted page from your server and confirm the resulting customer and subscription.

If your plan has a redirect URL, use the success callback to control navigation in your application instead of relying on the hosted checkout redirect.

Reference

For configuration details and all three integration paths, see Embedded Checkout.
For callback behavior, see setCheckoutCallbacks in the Chargebee.js Reference.
To open checkout as an overlay instead, see Create a new subscription with Chargebee Checkout.