Integration options

Chargebee offers the following options to integrate the Checkout based on your application or website's framework and business model:

• Hosted Pages API: Recommended if you want to authenticate the user on your end, override payment-related information, handle returning users, and collect additional information.
• Drop-in Script.
• Via Payment Link.

Regardless of the integration option you choose, to embed checkout in your website or application, use embedded checkout with Chargebee.js to mount checkout in a container on your page. Do not place hosted page URLs in your own iframe elements—Chargebee.js creates and manages the iframe for you.

When to use API vs. drop-in script

Hosted Pages API

Using the Hosted Pages API to create in-app checkout is the recommended approach when you already maintain a user-management or authentication system.

Benefits of using API integration:

• Manage authentication and collect additional information in your application or website.
• Override plan and addon pricing during checkout.
• Optimize trial tenure. For example, you can offer a 14-day trial to one customer and a one-month trial to another.

To learn more about the integration and implementation of Checkout via API, read our developer documentation.

You can use Checkout via APIs for the following workflows:

• Checkout for new subscriptions
• Checkout for existing subscription upgrades
• Checkout for one-time purchases

For end-to-end walkthroughs with server and client code in Ruby, Node.js, Java, Python, PHP, jQuery, Vue, Angular, and React, see Create a new subscription with Chargebee Checkout and Upgrade an existing subscription with Chargebee Checkout.

Call flow

Host an HTTPS endpoint that calls the Chargebee Hosted Pages API and returns a hosted page object.

Your application then uses Chargebee.js to open the Checkout.

Set up Chargebee.js

Include the Chargebee.js script in your HTML page. You need to do this only once per page.

<script src="https://js.chargebee.com/v2/chargebee.js"></script>

In your JavaScript code, initialize Chargebee to get a Chargebee instance. Use this instance for every subsequent Checkout call.

var cbInstance = Chargebee.init({
  site: "site-name", // Your Chargebee site
  domain: "https://mybilling.acme.com" // Optional. Use this only if a custom domain is enabled for your site.
});

Anywhere else on the page, call Chargebee.getInstance() to retrieve the same instance instead of initializing again.

For the complete initialization reference, including publishable keys, see Set up Chargebee.js in the Chargebee.js Reference.

Open Checkout with the Hosted Pages API

Call openCheckout() on the Chargebee instance. Pass a hostedPage function that returns a promise resolving to the hosted page object your server generates.

var cbInstance = Chargebee.getInstance();
cbInstance.openCheckout({
  hostedPage: function() {
    return $.ajax({
      url: '/generate_hp_url',
      data: data,
      method: 'POST'
    });
  },
  success: function(hostedPageId) {
    // Pass this ID to your server to retrieve the subscription details.
  }
});

Checkout callbacks

openCheckout() accepts the following callbacks in addition to hostedPage:

For the full parameter reference, see openCheckout().

Create a hosted page on your server

1. Create an HTTPS endpoint on your server.
2. Generate the hosted page object using the API that matches your use case—Checkout new or Checkout existing.
3. Return the hosted page object to the client.

post '/generate_hp_url' do
  # Use the checkout new or checkout existing API based on your use case.
  result = ChargeBee::HostedPage.checkout_new_for_items(params)
  return result.hosted_page.to_s
end

The endpoint returns a hosted page object:

{
  "id": "example_hosted_page_id",
  "type": "checkout_new",
  "url": "https://yourapp.chargebee.com/pages/v3/example_hosted_page_id/",
  "state": "created",
  "embed": true,
  "created_at": 1515494821,
  "expires_at": 1515498421
}

Drop-in script

The Drop-in Script is a plug-in type, easy-to-use solution that requires minimal developer help. You can easily create a checkout page by adding a script generated for the plan item on your HTML page.

Checkout integrated using the Drop-in Script is Level 1 PCI compliant. Therefore, you need to fill out this questionnaire before integrating.

The Drop-in Script also handles more advanced cases:

• Setting Checkout and portal callbacks.
• Modifying the plan quantity dynamically.
• Adding and removing addons on demand.
• Prefilling customer information and shipping information in the Checkout.

To use the Drop-in Script to integrate Checkout, follow these steps:

1. Click Settings > Configure Chargebee > Checkout and Self-Serve Portal > Integrate with Chargebee.
2. Select the Product Family, Plan, Currency, and Frequency from the drop-down list.
3. Add Addons and Charges if applicable using Add Addon and Add Charge options.
4. Select the Layout to control whether the Checkout opens in-app or as a full page.

5. Copy the Header Script and paste it within the <head> element of your website's HTML.

6. Copy the generated Checkout Button Code and hyperlink it in the Subscribe button on your website's HTML. This way, when a customer clicks the Subscribe button, the Checkout opens and displays the selected parameters of plan name, frequency, addons, and so on.

You can use Checkout via Drop-in for the following workflows:

• Checkout for new subscriptions
• Checkout for one-time purchases

For a step-by-step setup guide, including prefilling customer details and changing the cart at runtime, see the Drop-in Checkout with Chargebee.js tutorial.

The generated markup looks like this. The data-cb-item-<n> attributes carry the item price IDs you selected, and data-cb-layout carries the layout.

<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script src="https://js.chargebee.com/v2/chargebee.js" data-cb-site="acme-test" data-cb-business-entity-id="__dev__XpbBuzpT02K2kd24"></script>
  </head>
  <body>
    <h3>Checkout Drop-in</h3>
    <a href="javascript:void(0)" data-cb-layout="full_page" data-cb-type="checkout" data-cb-item-0="diamond-USD-monthly" data-cb-item-1="silver-pass-USD-monthly" data-cb-item-1-quantity="2">
      Subscribe
    </a>
  </body>
</html>

Cart customization

Use cart customization when your cart needs dynamic quantity changes or collects extra details through custom fields. It gives you full JavaScript control to add or remove plans, addons, and coupons, and to update quantities.

Set isItemsModel to true during initialization, then build the cart yourself instead of relying on the generated button attributes.

<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script src="https://js.chargebee.com/v2/chargebee.js"></script>
  </head>
  <body>
    <h3>Checkout Drop-in</h3>
    <button href="javascript:void(0)" onclick="openCheckout()">
      Subscribe
    </button>
  </body>
  <script>
    var cbInstance, cart;

    window.addEventListener('DOMContentLoaded', function() {
      cbInstance = Chargebee.init({
        site: "acme-test",
        isItemsModel: true,
      })

      cbInstance.setCheckoutCallbacks(function(cart) {
        return {
          success: function(hpid) {
            console.log('success', hpid)
          }
        }
      })

      cart = cbInstance.getCart()
    })

    function openCheckout() {
      const planPriceId = 'diamond-USD-monthly' // Plan price point ID identifies the product.
      const planPriceQuantity = 1
      const product = cbInstance.initializeProduct(planPriceId, planPriceQuantity)
      cart.replaceProduct(product);

      // Add an addon.
      product.addAddon({
        id: "silver-pass-USD-monthly", // Addon price point ID
        quantity: 2
      })

      // Add a coupon.
      product.addCoupon("fourty")

      // Change the plan quantity dynamically.
      product.setPlanQuantity(planPriceQuantity);

      // Remove an addon.
      product.removeAddon("silver-pass-USD-monthly");

      // Pass values for custom fields.
      product.setCustomData({referral: "yes", corporate_agent: "no"});

      // Open the Checkout.
      cart.proceedToCheckout();
    }
  </script>
</html>

Get the plan price point IDs, addon price point IDs, and the rest of the cart parameters from the Product object and Cart object references.

Open Checkout from your own button

You do not have to use the generated button. Build the cart yourself and open the Checkout from any element on your page.

document.addEventListener("DOMContentLoaded", function() {
  let cbInstance = Chargebee.getInstance();
  let cart = cbInstance.getCart();
  let product = cbInstance.initializeProduct("cbdemo_grow");
  cart.replaceProduct(product);
  document.getElementById("subscribe").addEventListener("click", function() {
    cart.proceedToCheckout();
  });
});

Via payment link

When you're looking for a simple and effective way to collect payments from your customers, a payment link can be an excellent solution.

Chargebee lets you create a custom URL to pass product details, customer information, and subscription data during checkout. The resulting Checkout URL can then be embedded into your application or website. You can also share this URL directly with customers through email and text messages.

To use the Payment Link to integrate Checkout, follow these steps:

1. Click Settings > Configure Chargebee > Checkout & Self-Serve Portal > INTEGRATE WITH CHARGEBEE > Via Payment Link

   

2. Choose the Business Entity if applicable. Learn more about multiple business entities.

3. Choose Checkout Type.

   1. If Subscription,
      1. Select the Product family, Plan, Currency, and Frequency from the drop-down list.
      2. Add Addons and Charges if applicable using Add addon and Add charge options.
      3. You can also add any parameters to pass additional information to the customer or subscription. Sample URL:

      https://honeydukes-test.chargebee.com/hosted_pages/checkout?subscription_items[item_price_id][0]=cbdemo_advanced-USD-monthly&subscription_items[quantity][0]=1&customer[first_name]=Minerva&customer[last_name]=McGonagall&subscription[cf_butterbeer_type]=Frozen Butterbeer

   2. If One-Time Payment:
      1. Choose Currency.
      2. Add Charges if applicable using Add charge options. Sample URL:

      https://honeydukes-test.chargebee.com/hosted_pages/checkout?subscription_items[item_price_id][0]=cbdemo_setup-charge-USD&subscription_items[quantity][0]=1&customer[first_name]=Minerva&customer[last_name]=McGonagall

List of supported query parameters

Here is an API spec of query parameters supported, which can be used in the plan URL:

You can integrate hosted checkout via Payment Link for the following workflows:

• Checkout for new subscriptions
• Checkout for one-time purchases