Two-step checkout with pass-through parameter

Watch Video

If you need to capture lot of information during checkout, a two-step is more elegant way to do it, than a long form checkout.
You can capture additional information on your website and then use Chargebee to handle the sensitive card information seamlessly using the two-step checkout.
Chargebee's theme support   ensures that you carry over your branded website's design into the payment page.

Alternative options

You have a few other options too:

  • 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 the API to create the subscriptions. But with this mode of integration, you will need to take care of the PCI compliance requirements.

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.

Getting the shipping address details along with the payment details on the same form makes it quite lengthy. Instead we opt for a 2 step checkout flow.


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 

In the signup page we get the non sensitive information such as email, phone number and address fields.

Now lets switch to 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 sign up request, we invoke Chargebee's Checkout New Subscription API. 
Since the API does not take in the shipping address information, we create a JSON-encoded pass thru parameter.

We pass the customer information along with the shipping address (as pass thru) to Chargebee.

Forward user to the checkout page 

The API response will have hosted page resource . The URL returned in hosted page response is sent as ajax response to the client.

Implement 'Return 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.

We still have to update the shipping address for the subscription. We do this by fetching the JSON-encoded address that we stored in the pass thru parameter from the hosted page resource in the response   and then calling the update address api .

Redirecting to a '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.
In the 'thank you' page we again fetch the shipping address (using Retrieve Address API  ) to show to the customer.


Implementing a two step checkout flow is very easy. You just need to follow the steps below:

  1. Design the page for the first step of the checkout flow that captures non sensitive account information from the user.
  2. On the server side write the code to handle the submit. Call the Checkout New Subscription API   in Chargebee and pass the subscription details such as plan and other information captured in the first step.
  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. On the 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 (e.g a thank you page).

Validation and Error Handling

Here's how we validate user inputs and handle API call errors in this demo:

  • Client Side Validation: We use the jQuery form validation  plugin to check whether the user's input in fields(email, zip code and phone number) is valid or not.

  • Server Side Validation: As this is a demo app we have skipped the server side validation of all input parameters. But we recommend you to perform the validation at your end.

  • General API Errors: Chargebee might return error responses due to various reasons such as invalid configuration. To identify specific reasons for all error responses you can check the API documentation  and also take a look at the error handler file to check how these errors can be handled.