Integration options

Chargebee offers the following options to integrate the hosted 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.
Plan-Specific URL.

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. It gives you control to override predefined information for a particular instance, such as changing the price of an item or providing an additional trial period.

Note:

The API generates a Checkout URL that expires 3 hours after creation.

Benefits of using API integration:

Manage authentication and collect additional information in your application or website.
Override plan and add-on 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.

Example

Here's an example of when you might choose Checkout via API over the Drop-in Script:

Jenna runs a digital weight loss and fitness app. She wants to collect user information such as the client's height, weight, food habits, and so on, along with their address and email, and store it in her database instead of Chargebee. She would still like to use Chargebee's Checkout as she does not want to handle the details of PCI Compliance.

Jenna can use the API integration to collect additional information on the frontend and rely on Chargebee's Hosted Pages API for payment details.

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

You can use hosted checkout via APIs for the following workflows:

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.

Note:

You should review the following documents from the above page before integrating Checkout using the Drop-in Script:

SAQ Instructions and Guidelines
Understanding SAQs for PCI DSS

The SAQs must be filled out based on the applicability as per the guideline document and shared with the payment gateway. No document needs to be submitted to Chargebee.

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

Click Settings > Configure Chargebee > Checkout and Self-Serve Portal > Integrate with Chargebee.

Select the Plan and Add-on from the drop-down list.

Copy the Header script and paste it within the <head> tag of the HTML page.

Copy the Checkout Button Code and paste it in the body of the HTML page.

Here is a sample checkout:

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

Checkout for new subscriptions
Checkout for one-time purchases

Learn more on how to integrate Checkout using the Drop-in Script.

Plan-specific URL

You can manually create a checkout URL and embed it in your application or website's Checkout button. When the checkout button is clicked, the Checkout is displayed.

This approach is the easiest. Through this integration, the checkout window opens in a new tab. Products in the Checkout URL cannot be altered during checkout since the integration does not support dynamic modification. Complex business logic such as price override, user authentication, and so on, are not possible through this integration.

Note:

In this integration approach, if the user clicks the checkout link when on a WebView tab, the checkout window will not work. This is because the integration only supports opening the checkout window in a new tab.

Example for a plan-specific URL:

https://{your-site}/hosted_pages/plans/no-trial
?coupon_ids[0]=fifty
&addons[id][0]=day-pass
&addons[quantity][0]=2
&customer[email]=vivek@chargebee.com
&customer[cf_test]=customer%20custom%20field
&customer[cf_date]=1991-09-16
&subscription[cf_sub_test]=subscription%20custom%20field

Here's the syntax to create a plan-specific URL:

https://<site-name>.chargebee.com/hosted_pages/plans/<plan-id>

Replace the <site-name> and <plan-id> placeholders with your Chargebee site subdomain and Plan ID. For example, if the site name is docstest-test and the plan ID is sapphire, then this is how the URL would look:

https://docstest-test.chargebee.com/hosted_pages/plans/sapphire

This approach is recommended if your application or website's code does not accept JavaScript.

List of supported query parameters

Section	URL Parameter
Plan	`/hosted_pages/plans/<plan_id>/subscription[plan_quantity]`
Addon	`addons[id][0]` `addons[quantity][0]`
Coupons	`coupon_ids[0]`
Customer	All parameters available for Checkout a new subscription. Exceptions: `taxability`, `consolidated_invoicing`
Subscription	`subscription[plan_quantity]` `subscription[start_date]` `subscription[<custom_field_name>]`
Billing address	All parameters available here. Exceptions: `validation_status`
Shipping Address	All parameters available here. Exceptions: `validation_status`