ChargebeeAPI

Hosted pages

Hosted pages are the easiest and most secure way to integrate chargebee with your website. By using hosted pages, you can avoid the sensitive card information passing through your server and be compliant with most of the PCI DSS requirements.

When you request for a hosted page, a secure and unique URL will be returned which you could either embed or redirect depending upon the embed parameter value that you had passed.

Specifying "embed" parameter as true allows you to embed the "hosted page" in an iframe in your own website. This helps you provide the best experience to your user as they do not have to leave your website to provide card information. There are a few limitations:

  • Your site URL must be embedded with HTTPS.
  • Set the appropriate height and width for the iframe to avoid scrolling.

To use the hosted pages, you must configure Redirect URL in the Chargebee web interface under Hosted Pages Settings > Configuration. The configured redirect URL will be called with the following parameters after user had submitted the page.

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

After the Redirect URL is called by Chargebee with the above parameters, the details of the hosted page can be fetched using Retrieve a hosted page API. The content attribute will have the details about the customer, subscription, card and invoice based on the type of the hosted page.

Checkout New Subscription:

  • Customer - The details about the new customer created.
  • Subscription - The details about the new subscription created.
  • Card - The details about the card provided while subscribing.
  • Invoice - The details about the invoice, if one is generated.

Checkout Existing Subscription:

  • Customer - The updated details of the customer.
  • Subscription - The updated details of the subscription.
  • Card - The details about the card provided while subscribing.
  • Invoice - The details about the invoice, if one is generated.

Update Payment Method:

  • Customer - The details about the customer for whom the card was updated.
  • Card - The details about the updated card. It will be present only if the type of payment method is card.

When an embedded hosted page is cancelled by your end user, the content attribute will have the unmodified details of customer, subscription and card resources.

Sample Hosted pageJSON

API Index URL

https://[site].chargebee.com/api/v2/hosted_pages

Hosted pages attributes

id
optional, string, max chars=70

Unique identifier generated for each hosted page requested.

type
optional, enumerated string

Type of the requested hosted page.

Possible Enum Values
checkout_new

Checkout new Subscription

checkout_existing

Checkout existing Subscription

update_payment_method

Update Payment Method for a Customer

manage_payment_sources

Manage Payments for a customer

collect_now

Collect Unpaid Invoices for a Customer

url
optional, string, max chars=250

Unique URL for the hosted page that will be included in your website.

state
optional, enumerated string, default=created

Indicating the current state of the hosted page resource.

Possible Enum Values
created

Indicates the hosted page is just created.

requested

Indicates the hosted page is requested by the website

succeeded

Indicates the hosted page is successfully submitted by the user and response is sent to the return url.

cancelled

Indicates the page is cancelled by the end user after requesting it.

acknowledged

Indicates the succeeded hosted page is acknowledged.

pass_thru_content
optional, string, max chars=2048

This attribute allows you to store custom information with the hosted_page object. You can use it to associate specific data with a hosted page session. For example, you can store the ID of the marketing campaign that initiated the user session. After a successful checkout, when the customer is redirected, you can retrieve the hosted page ID from the redirect URL's query parameters. Using this ID, you can fetch the hosted page and perform actions related to the success of the marketing campaign.

embed
required, boolean, default=true

If true then hosted page formatted to be shown in iframe. If false, it is formatted to be shown as a separate page.

Note : For in-app checkout, default is false.

created_at
optional, timestamp(UTC) in seconds

Indicates when this hosted page url is generated.

expires_at
optional, timestamp(UTC) in seconds

The date and time when the hosted page URL expires. After this timestamp, the page can no longer be accessed. The expiration period depends on the type of hosted page:

  • For checkout_new, checkout_existing, and checkout_one_time, the URL expires 3 hours after the page is created.
  • For collect_now and manage_payment_sources, the URL expires 5 days after creation.
content
required, jsonobject

This attribute will be returned only during retrieve hosted page API call and also the retrieved hosted page resource state should be either in "succeeded" or "cancelled" state. If hosted page state is "succeeded", then the subscription, customer, card & invoice(optional) resources during checkout can be obtained. If hosted page is state is "cancelled", then it will be empty i.e no information about checkout.

updated_at
optional, timestamp(UTC) in seconds

Timestamp indicating when this hosted page was last updated.

resource_version
optional, long

The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds.

checkout_info
optional, jsonobject

Customer Info (email, first name and last name) given in the checkout page used for tracking abandoned carts. Learn more

business_entity_id
optional, string, max chars=50

The ID of the business entity created for the site. For Product Catalog 1.0, all the site data is tied to this business entity.

Note

Multiple Business Entities is a feature available only on Product Catalog 2.0.