Implement a simple checkout using a hosted payment page

Watch Video

Chargebee's customizable hosted checkout pages provides you with a seamless checkout experience to match your website and all the elements required to assure customers of a safe checkout experience & increase your signup conversions. The theme support   ensures that you incorporate your branding elements from your website's design into the payment page. Since it is 'hosted' by Chargebee, no sensitive information passes through your servers, thus completely reduces the security requirements, PCI compliance and more.

Alternative options

Here are a few other options:

  • If your requirement is simple, you could directly use the plan based checkout page . The advantage is that you do not need to write any code. Just copy the hosted page URL and paste it onto your website. You can also pass additional information via parameters.
  • You can build your own checkout form and use API to create the subscription. But with this mode of integration, you will need to take care of the PCI compliance requirements.
  • You could also use the same flow used in this tutorial but embed the checkout form into your website by using the embed  option.

Honey Comics - Demo Application 

'Honey Comics', our demo application, is a fictitious online comic book store providing a subscription service for comics. We send comic books every week to subscribers. Users can sign up for a subscription from the website by providing their credit card information. Subscriptions have trial period and hence the subscriber is not charged immediately. Instead the subscription will remain in trial until the trial period is over. They will be charged automatically (by chargebee) at the end of the trial period.


To try out the tutorial yourself, you'll need the following:

  • A Chargebee account. Signup for a free trial if you don't have one.
  • A plan with a trial period in your test site in Chargebee. You can setup the plan using the "Setup Configuration" option in the index page if you have downloaded code and started the tutorials locally.
  • Your Chargebee API key for your test site.

Build the signup page 

Build a page where users can signup. In our demo application, we've assumed that there will only be a single plan. Hence a simple link will suffice. When the user clicks on subscribe, the request will be sent to the server.

  • php
  • Ruby
  • Java
  checkout_new/index.html  -   View full code
<a href="/checkout_new/checkout" class="btn btn-success btn-lg">Subscribe</a>

Now lets switch to the server side implementation

Setup the client library 

We first have to download and import  the client library of our choice. Then we need to configure the client library with our test site and our test api key.

For the tutorials we have configured the site and the credentials in a properties file from which the client library is configured at the webapp is initialized.

For the tutorials we have configured the site credentials in config/environments/development.rb

We setup the client library in config/initializers/chargebee.rb

For the tutorials we have configured the site credentials in Config.php which is included in other php files.

Request a hosted page URL 

When the server receives the signup request, we invoke Chargebee's checkout new subscription API  . The API will return a hosted page resource response  containing the URL to forward the user to.

Forward user to the checkout page 

We send a 302 redirect response to the user's browser with location set to the URL.

Implement 'Redirect URL' 

Once the user is on the checkout page and has completed the checkout process, Chargebee will send the user back to your server based on the redirect URL that had been passed previously to the hosted page api call.

Additionally, the following parameters will be added to the redirect URL:

id - unique identifier of the hosted page resource.
state - succeeded, failed or cancelled.

The ‘id' parameter can be used to call the ‘acknowledge hosted page'  API. The response  from this API will have the details provided in the checkout page.


It is recommended that you use ‘acknowledge hosted page' API when you are syncing data using the returned URL. This will ensure that multiple redirects of redirect URL with the same hosted page id will not create duplicate entries at your end. Acknowledge API can be called only once for succeeded hosted page. After calling this the state of the hosted page will be changed from succeeded to acknowledged. And if the same api call is made on the same hosted page id again error will be thrown.

Incase the users cancel the checkout, Chargebee will redirect them to the cancel URL that had been passed previously to the hosted page api call. In our case, as we have passed the signup page as the cancel URL, the users will be redirected back to the signup page.

Redirecting to 'Thank you' page 

After we've fetched the hosted page, we redirect the user to a simple thank you page. You could add the subscription to your database (skipped in demo) and redirect to the appropriate page.


Here is the summary of steps you need to follow:

  1. Add a simple signup link.
  2. On the server side write the code to receive the signup request. Call the checkout new subscription API   in Chargebee and pass the subscription details such as plan.
  3. The response to the API call will contain the URL for your hosted checkout page. Forward the user to that URL
  4. Once the checkout is finished, Chargebee will forward the user back to your application using the return URL  configured in Chargebee. In server side handle the redirect request and add the subscription to your database by fetching the details from Chargebee.
  5. Forward the user to the appropriate page (such as thank you page).