# Hosted pages

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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](/docs/api/v1/hosted_pages/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](/docs/api/v1/hosted_pages/checkout-new-subscription):

-   [Customer](/docs/api/v1/customers/customer-object) - The details about the new customer created.
-   [Subscription](/docs/api/v1/subscriptions/subscription-object) - The details about the new subscription created.
-   [Card](/docs/api/v1/cards/card-object) - The details about the card provided while subscribing.
-   [Invoice](/docs/api/v1/invoices/invoice-object) - The details about the invoice, if one is generated.

[Checkout Existing Subscription](/docs/api/v1/hosted_pages/checkout-existing-subscription):

-   [Customer](/docs/api/v1/customers/customer-object) - The updated details of the customer.
-   [Subscription](/docs/api/v1/subscriptions/subscription-object) - The updated details of the subscription.
-   [Card](/docs/api/v1/cards/card-object) - The details about the card provided while subscribing.
-   [Invoice](/docs/api/v1/invoices/invoice-object) - The details about the invoice, if one is generated.

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 page

```json
{
  "created_at": 1517506797,
  "embed": true,
  "expires_at": 1517510397,
  "id": "__test__KfW0lW3V4e8fhHtugBdLaUcuJL60OycPv",
  "layout": "in_app",
  "object": "hosted_page",
  "state": "created",
  "type": "checkout_new",
  "url": "https://yourapp.chargebee.com/pages/v3/__test__KfW0lW3V4e8fhHtugBdLaUcuJL60OycPv/checkout",
  "content": {}
}
```

## Hosted pages attributes

## Input Parameters

- `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_card`
      Update Card for a Customer
    - `checkout_onetime_charge`
      Checkout One time Charge
    - `checkout_onetime_addons`
      Checkout One time Addons
    - `checkout_one_time`
      Checkout one time

- `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.

- `pass_thru_content` (optional, string, max chars=2048)
  You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.

- `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](https://www.chargebee.com/docs/checkout-v3.html) 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)
  Indicates when this hosted page url will expire. After this, the hosted page cannot be accessed.

- `layout` (optional, enumerated string)
  Specifies the [UI layout](https://www.chargebee.com/docs/billing/2.0/hosted-capabilities/hosted-checkout#ui-layout-options) for the hosted page. The value is always `in_app` for this API version.
  
  Applicable only when `type` is `checkout_new` or `checkout_existing`.
  Possible enum values:
    - `in_app`
      The hosted page is rendered in the in-app layout.
    - `full_page`
      Not supported for this API version. Upgrade to the [latest](/docs/api/hosted_pages/hosted-page-object#layout) API version to use this layout.

- `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.