Chargebee Checkout: Choosing a Layout, Then Handling What Happens After Payment
Chargebee Checkout is one hosted flow, from cart through payment to the thank-you step, offered in two layouts: an in-app modal that Chargebee.js opens over your page, and a full-page checkout you can style to match your site or embed in it. If you'd rather draw the payment form yourself, Payment Components do that. Whichever you choose, the customer's account in your own app is set up by code you write.
Pick the layout (in-app or full-page) in Chargebee's settings:
Settings › Configure Chargebee › Checkout & Self-Serve PortalIn-app: a modal that Chargebee.js loads in an iframe it manages, built with phones in mind. Don't wrap it in an iframe of your own.
Full-page: the layout you can style and embed. To embed it, mount it in a container with Chargebee.js. Never put a hosted page URL in your own iframe.
Payment Components: payment fields you mount inside your own form, covering cards, Apple Pay, Google Pay, PayPal, direct debit and more. They need a publishable key in Chargebee.init. Card Components are deprecated.
Keys: hosted pages are created on your server with a full-access key. The browser only gets your site name, plus the publishable key when you use Payment Components.
Which Chargebee checkout suits the signup you have
Server-created checkout, from the click to a working account
- 1
Create the hosted page on your server
When the customer clicks, your server asks Chargebee's hosted pages API for a new-subscription checkout with the plan they picked, using a key that never reaches the browser. Put anything you want back afterwards, such as your own user ID or a campaign, in
pass_thru_content, up to 2,048 characters. - 2
Open it with Chargebee.js
openCheckouttakes ahostedPagefunction that calls your server and resolves to that hosted page. Callbacks fire when it loads, when the customer closes it and when it succeeds, the last one with the hosted page ID. - 3
Retrieve the result before you trust it
A full-page checkout sends the customer to your
redirect_urlwith the hosted pageidandstate. Retrieve that hosted page on your server. Its content holds the customer, subscription and invoice you'll set the account up from.Watch for: treating the query string as proof of payment. Anyone can type
state=succeededinto an address bar. - 4
Set the account up once
Create the user or workspace, apply the plan's limits, and store the Chargebee customer and subscription IDs. Hosted pages have an
acknowledgedstate for marking one as processed. Use it, or your own record, so a second callback doesn't create a second account. - 5
Back it up with the subscription event
A customer can pay and close the tab before the redirect finishes. Have your webhook handler set up the account from Chargebee's
subscription_createdevent as well, and let whichever arrives second find the work already done.
Chargebee checkout and portal questions
Can customers change their own plan through Chargebee's portal?
Yes, if you've allowed it in the portal settings. Customers can view invoices, update payment methods, and upgrade, downgrade or cancel. To open the portal from inside your app without a second login, your server creates a portal session, Chargebee.js takes it through setPortalSession, then createChargebeePortal opens it. That needs SSO turned on in the portal settings, and the session ends after an hour if it isn't logged out first.
Can I customize the look of Chargebee's hosted checkout or customer portal?
Partly. The full-page layout is the one built to match your site, and it can be embedded. The in-app modal is preconfigured. Branding for checkout and the portal is set in Chargebee's settings rather than in code, and layout changes beyond those settings are limited.
Does Chargebee support PayPal on the hosted checkout page?
Yes, as PayPal Express Checkout, once PayPal is connected as a payment gateway on your Chargebee site. It's also among the methods Payment Components can show if you build your own form.
Do I need a developer to set up Chargebee's hosted checkout?
Not for the standard flow you configure in Chargebee's settings. You do once checkout opens from your own buttons through Chargebee.js, hosted pages are created on your server, or Payment Components sit in your own form, and always for the step that creates the customer's account in your app.
Who wires a Chargebee checkout into our own app's signup?
n-frames builds that part: the server endpoint that creates hosted pages, the retrieve-and-provision step after payment, the subscription_created handler that backs it up, and the portal session that lets customers manage billing from inside your app. When they change plans in the portal, the same handler updates access in your product and the record in your CRM.