Update payment method using hosted pages

Watch Video

One of the important features needed for a subscription business is to allow your users to add/update their payment method securely. Chargebee's customizable hosted update payment method page will help you implement it quickly. The theme support ensures that you carry over your branded website's design. Since it is 'hosted' at Chargebee, your servers don't handle any sensitive card information. This drastically reduces the security requirements, PCI compliance and more.

Alternative options
  • We recommend you to use customer portal where your customers will be able to view and update their information including their payment options.
  • You can build your own add/update payment method form and use the API   to pass on the information to Chargebee . 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. In order to let customers try the service, we provide them with a free trial period for a month. The user could become a paid user by adding his/her payment method (such as card) in the self service page. The user will be charged automatically at the end of the trial period.

BTW, in our sample implementation, to simplify code,

  • We won't be using any database.
  • We will not have real login implementation.
  • We will assume the email id to be the Chargebee id for that customer.


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 Chargebee. You can setup the plan and subscription for the demo 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.

We should already have a trial subscription in Chargebee for that user. We could create the subscription via the API or via Chargebee's Admin UI. In addition to that, they should be signed-in into our application so that our system is able to identify the user.

Design a profile page 

Design a page where users can view their subscription details and also have the option to add/update payment method. In our demo application, we've assumed that there will only be a single plan and the user is currently in trial.
We show the subscription details fetched from Chargebee based on the logged-in email id which is used as the id in Chargebee.
When the user clicks on the add card link, the request will be sent to the server.

Now lets see the demo app's 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.

Implement a profile page 

We have implemented a simple profile page displaying the account and subscription information along with the payment method details.
We have fetched the subscription details using the retrieve subscription api.  The API response  returns the customer,  subscription  and card  details.

We use the subscription details response to display the information.

We either ask the user to add payment method if there is no card associated.

If the payment method is already present, we show the existing payment details and allow the user to update the card.

Request a hosted page URL 

When the server receives the update request, we invoke Chargebee's Hosted Page > update payment method 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 with location set to the URL.

Implement 'Return URL' 

Once the user has finished adding(or updating) the payment method ,Chargebee will send the user back to our server using the redirect URL that we had specified in the 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 canceled. Do not use this parameter. Rather fetch it from Chargebee

We should use the "id" parameter to acknowledge Hosted Page API . The API response  will contain the customer details along with the non-sensitive payment method details

Redirect back to profile page 

After we've fetched the hosted page and got the details of the user, we redirect the user back to the profile page.


Integrating an update payment method functionality is very easy. You just need to follow the steps below:

  1. Build a simple self service page which would allow users to add/update their update payment method.
  2. From your server, forward the add/update request to Chargebee by calling the Hosted Pages->Update Payment method API. 
  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 payment method has been added/updated by the user, Chargebee will forward the user back to your application using the redirect URL specified by you in the api call. On the server side handle the redirect request and update your database if required by fetching the subscription details from Chargebee. Finally, forward the user to the appropriate page (e.g thank you page) or back to the self service page.