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 & 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. Drawbacks are

• Your site should also be in https
• You have to be careful with height and width of the iframe otherwise users might get scroll.

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 & invoice based on the type of the hosted page.

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

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

For 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 & card resources.

Sample hosted page [ JSON ]

Hosted page to accept card details from the subscriber and create a new subscription. This is similar to our server to server API Create a Subscription.

When the redirect URL is notified of the result, we would advise you to retrieve the subscription and verify the details.

Related Tutorials

• Create a subscription using Chargebee's hosted page

Notes

# checkout a new subscription with customer details.
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new \
     -u {site_api_key}:\
     -d customer[email]="john@user.com" \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[locale]="fr-CA" \
     -d customer[phone]="+1-949-999-9999" \
     -d subscription[plan_id]="no_trial" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

# checkout a new subscription with customer details.
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new \
     -u {site_api_key}:\
     -d customer[email]="john@user.com" \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[locale]="fr-CA" \
     -d customer[phone]="+1-949-999-9999" \
     -d subscription[plan_id]="no_trial" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

# checkout a new subscription with addons.
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new \
     -u {site_api_key}:\
     -d customer[email]="john@user.com" \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[locale]="fr-CA" \
     -d customer[phone]="+1-949-999-9999" \
     -d subscription[plan_id]="no_trial" \
     -d addons[id][0]="sub_monitor" \
     -d addons[unit_price][0]=100 \
     -d addons[quantity][0]=2

# checkout a new subscription with customer card details.
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new \
     -u {site_api_key}:\
     -d customer[email]="john@user.com" \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[locale]="fr-CA" \
     -d customer[phone]="+1-949-999-9999" \
     -d subscription[plan_id]="no_trial" \
     -d card[gateway_account_id]="gw___test__KyVnGlSBWmAIk2Ph"

Sample Response [ JSON ]

{"hosted_page": {
    "created_at": 1517505996,
    "embed": true,
    "expires_at": 1517509596,
    "id": "__test__znukwBn17fojRqcSm5uZtxxn99WgF5gcu",
    "object": "hosted_page",
    "resource_version": 1517505996000,
    "state": "created",
    "type": "checkout_new",
    "updated_at": 1517505996,
    "url": "https://yourapp.chargebee.com/pages/v2/__test__znukwBn17fojRqcSm5uZtxxn99WgF5gcu/checkout"
}}

{"hosted_page": {
    "created_at": 1517506000,
    "embed": true,
    "expires_at": 1517509600,
    "id": "__test__PnEJ6KNB31zqS76BCwfZs4OCoag4ecjA",
    "object": "hosted_page",
    "resource_version": 1517506000000,
    "state": "created",
    "type": "checkout_new",
    "updated_at": 1517506000,
    "url": "https://yourapp.chargebee.com/pages/v2/__test__PnEJ6KNB31zqS76BCwfZs4OCoag4ecjA/checkout"
}}

{"hosted_page": {
    "created_at": 1517505999,
    "embed": true,
    "expires_at": 1517509599,
    "id": "__test__oPHcd2RuF4jrRJ0yW7U6akQHKgOuiV8OB",
    "object": "hosted_page",
    "resource_version": 1517505999000,
    "state": "created",
    "type": "checkout_new",
    "updated_at": 1517505999,
    "url": "https://yourapp.chargebee.com/pages/v2/__test__oPHcd2RuF4jrRJ0yW7U6akQHKgOuiV8OB/checkout"
}}

URL Format POST

Create a Chargebee hosted page to accept payment from a customer and checkout non-recurring addons and one-time charges.

The following steps describe how best to use this API:

1. Call this endpoint, providing non-recurring addons, one-time charges, coupons and a host of other details such as billing and shipping addresses of the customer, to be prefilled on the checkout page.
2. Send the customer to the Checkout url received in the response.
3. Once they complete checkout, the non-recurring addons and one-time charges are automatically invoiced against the respective customer record in Chargebee, and they are redirected to the redirect_url with the id and state attributes passed as query string parameters.
4. Retrieve the hosted page at this stage to get the invoice details.

# Creates a checkout with non-recurring addon
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_one_time \
     -u {site_api_key}:\
     -d customer[id]="__test__3Nl7Oe7SJWjx905b" \
     -d addons[id][0]="non_recurring_addon" \
     -d addons[unit_price][0]=2000 \
     -d addons[quantity][0]=2 \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d shipping_address[first_name]="John" \
     -d shipping_address[last_name]="Mathew" \
     -d shipping_address[city]="Walnut" \
     -d shipping_address[state]="California" \
     -d shipping_address[zip]="91789" \
     -d shipping_address[country]="US"

# Creates a checkout with non-recurring addon
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_one_time \
     -u {site_api_key}:\
     -d customer[id]="__test__3Nl7Oe7SJWjx905b" \
     -d addons[id][0]="non_recurring_addon" \
     -d addons[unit_price][0]=2000 \
     -d addons[quantity][0]=2 \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d shipping_address[first_name]="John" \
     -d shipping_address[last_name]="Mathew" \
     -d shipping_address[city]="Walnut" \
     -d shipping_address[state]="California" \
     -d shipping_address[zip]="91789" \
     -d shipping_address[country]="US"

# Creates a checkout with one-time charge
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_one_time \
     -u {site_api_key}:\
     -d customer[id]="__test__3Nl7Oe7SJWjxt75r" \
     -d charges[amount][0]=1000 \
     -d charges[description][0]="Support Charge"

# Creates a checkout with non-recurring addon and one-time charge
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_one_time \
     -u {site_api_key}:\
     -d customer[id]="__test__3Nl7Oe7SJWjxX15j" \
     -d addons[id][0]="non_recurring_addon" \
     -d addons[unit_price][0]=2000 \
     -d addons[quantity][0]=2 \
     -d charges[amount][0]=1000 \
     -d charges[description][0]="Support Charge"

Sample Response [ JSON ]

{"hosted_page": {
    "created_at": 1517490515,
    "embed": false,
    "expires_at": 1517494115,
    "id": "__one_time_checkout___test__ndXKBDiEMD5gWNAHT2FC8FpfdWjRJ60c",
    "object": "hosted_page",
    "resource_version": 1517490515264,
    "state": "created",
    "type": "checkout_one_time",
    "updated_at": 1517490515,
    "url": "https://yourapp.chargebee.com/pages/v3/__one_time_checkout___test__ndXKBDiEMD5gWNAHT2FC8FpfdWjRJ60c/"
}}

{"hosted_page": {
    "created_at": 1517490517,
    "embed": false,
    "expires_at": 1517494117,
    "id": "__one_time_checkout___test__cdp2X2Mcd1KVekorXqI7LemaGacuZfc3klU",
    "object": "hosted_page",
    "resource_version": 1517490518015,
    "state": "created",
    "type": "checkout_one_time",
    "updated_at": 1517490518,
    "url": "https://yourapp.chargebee.com/pages/v3/__one_time_checkout___test__cdp2X2Mcd1KVekorXqI7LemaGacuZfc3klU/"
}}

{"hosted_page": {
    "created_at": 1517490516,
    "embed": false,
    "expires_at": 1517494116,
    "id": "__one_time_checkout___test__RrskcdKPskXT8MIZnccuar99DcuXUyY5eZ6",
    "object": "hosted_page",
    "resource_version": 1517490516676,
    "state": "created",
    "type": "checkout_one_time",
    "updated_at": 1517490516,
    "url": "https://yourapp.chargebee.com/pages/v3/__one_time_checkout___test__RrskcdKPskXT8MIZnccuar99DcuXUyY5eZ6/"
}}

URL Format POST

You can checkout an existing subscription(typically in the trial state) by passing in the plan, quantity and addon details(like Update a Subscription)

When the redirect URL is notified of the result, we would advise you to retrieve the subscription and verify the details.

Related Tutorial

• Upgrade existing subscription using Chargebee's hosted page

Notes

curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_existing \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWmCOu2tC" \
     -d subscription[plan_id]="sub_plan1"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_existing \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWmCOu2tC" \
     -d subscription[plan_id]="sub_plan1"

# checkout an existing subscription with addons.
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_existing \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWmCoF2tJ" \
     -d subscription[plan_id]="no_trial" \
     -d addons[id][0]="sub_ssl" \
     -d addons[unit_price][0]=200

Sample Response [ JSON ]

{"hosted_page": {
    "created_at": 1517505988,
    "embed": true,
    "expires_at": 1517509588,
    "id": "__test__yY8QV6GaiRmIYi3JV6ZBHulNfEVj6LjG",
    "object": "hosted_page",
    "resource_version": 1517505988000,
    "state": "created",
    "type": "checkout_existing",
    "updated_at": 1517505988,
    "url": "https://yourapp.chargebee.com/pages/v2/__test__yY8QV6GaiRmIYi3JV6ZBHulNfEVj6LjG/checkout"
}}

{"hosted_page": {
    "created_at": 1517505989,
    "embed": true,
    "expires_at": 1517509589,
    "id": "__test__7HSjiTQGqB7Bg3wHdjHRWZKu0Pcda4mcd0",
    "object": "hosted_page",
    "resource_version": 1517505989000,
    "state": "created",
    "type": "checkout_existing",
    "updated_at": 1517505989,
    "url": "https://yourapp.chargebee.com/pages/v2/__test__7HSjiTQGqB7Bg3wHdjHRWZKu0Pcda4mcd0/checkout"
}}

URL Format POST

Note: If you're using Checkout V3, use Manage Payment Sources API to request your customers to update their payment method details or change their payment method.

Using this API, you can request your customers to update their payment method details or change their payment method. This is used in scenarios like customers updating their payment methods before the end of trial or customers switching among payment methods.

When this API is invoked, it returns a hosted page URL. When the customers are directed to this URL, they will be able to change/update their payment methods.

Depending on the payment methods (Card, PayPal Express Checkout, Amazon Payments) that you offer your customers, they will find options to switch among the various methods of payment.

• If the card[gateway] parameter is passed, and the customer chooses Card as a payment method, then the card details are stored in the gateway which is passed. However, if the card[gateway] parameter is passed and the customer chooses PayPal Express Checkout/Amazon Payments as a payment method, the gateway passed will be ignored.
• The option of embedding into an iframe is not supported for PayPal Express Checkout and Amazon Payments as customers are redirected to the respective website pages. Hence if you have PayPal Express Checkout/Amazon Payments configured and pass the parameter embed=true, this will result in an unsuccessful API request. Also, if you have all the three payment methods (Card, Paypal Express Checkout and Amazon Payments) configured and pass the parameter embed=true, the returned hosted page URL will show only Card Payment as a payment method.

curl  https://{site}.chargebee.com/api/v2/hosted_pages/update_payment_method \
     -u {site_api_key}:\
     -d customer[id]="__test__KyVnHhSBWmKhy2uX" \
     -d card[gateway_account_id]="gw___test__KyVnGlSBWmAIk2Ph"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/update_payment_method \
     -u {site_api_key}:\
     -d customer[id]="__test__KyVnHhSBWmKhy2uX" \
     -d card[gateway_account_id]="gw___test__KyVnGlSBWmAIk2Ph"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/manage_payment_sources \
     -u {site_api_key}:\
     -d customer[id]="__test__KyVnHhSBWmJIX2uE" \
     -d card[gateway_account_id]="gw___test__KyVnGlSBWmAIk2Ph"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/manage_payment_sources \
     -u {site_api_key}:\
     -d customer[id]="__test__KyVnHhSBWmJIX2uE" \
     -d card[gateway_account_id]="gw___test__KyVnGlSBWmAIk2Ph"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/collect_now \
     -u {site_api_key}:\
     -d customer[id]="__test__KyVnGlSBWmHH82Pw" \
     -d card[gateway_account_id]="gw___test__KyVnGlSBWmAIk2Ph"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/collect_now \
     -u {site_api_key}:\
     -d customer[id]="__test__KyVnGlSBWmHH82Pw" \
     -d card[gateway_account_id]="gw___test__KyVnGlSBWmAIk2Ph"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/accept_quote \
     -X POST  \
     -u {site_api_key}:\
     -d quote[id]="1"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/accept_quote \
     -X POST  \
     -u {site_api_key}:\
     -d quote[id]="1"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/extend_subscription \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWmIgw2u6" \
     -d billing_cycle=2 \
     -d expiry=14

curl  https://{site}.chargebee.com/api/v2/hosted_pages/extend_subscription \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWmIgw2u6" \
     -d billing_cycle=2 \
     -d expiry=14

curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift \
     -u {site_api_key}:\
     -d subscription[plan_id]="GiftPlan$100"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift \
     -u {site_api_key}:\
     -d subscription[plan_id]="GiftPlan$100"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/claim_gift \
     -u {site_api_key}:\
     -d gift[id]="__test__KyVnHhSBWmGdM2tv__test__21cdZvclBhOULyCT1SBUPDKjoXsuc3wdj"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/claim_gift \
     -u {site_api_key}:\
     -d gift[id]="__test__KyVnHhSBWmGdM2tv__test__21cdZvclBhOULyCT1SBUPDKjoXsuc3wdj"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/retrieve_agreement_pdf \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__KyVnHhSBWmKRg2uT"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/retrieve_agreement_pdf \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__KyVnHhSBWmKRg2uT"

curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__p541yXSwQO7jD2oRNFlBSvqU2s0oiWY0/acknowledge \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__p541yXSwQO7jD2oRNFlBSvqU2s0oiWY0/acknowledge \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/hosted_pages \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

curl  https://{site}.chargebee.com/api/v2/hosted_pages \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2