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:
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.
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 Existing Subscription:
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.
{
"created_at": 1517506797,
"embed": true,
"expires_at": 1517510397,
"id": "__test__KfW0lW3V4e8fhHtugBdLaUcuJL60OycPv",
"object": "hosted_page",
"state": "created",
"type": "checkout_new",
"url": "https://yourapp.chargebee.com/pages/v2/__test__KfW0lW3V4e8fhHtugBdLaUcuJL60OycPv/checkout"
}
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.
As mentioned before this behavior is very similar to the create subscription API call. All the web hook events will be fired only after the submission of payment details by the customer and successful creation of subscription.
Any errors related to the payment form that is submitted is handled as a response within the form so that the user is kept informed about the reason for failure to take corrective action.
# checkout a new subscription with customer details. curl https://{site}.chargebee.com/api/v1/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[phone]="+1-949-999-9999" -d subscription[plan_id]="no_trial"
redirect_url
after successful checkout,
we do not recommend relying on it for completing critical post-checkout actions.
This is because redirection may not happen due to unforeseen reasons.
Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout. 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.
As mentioned before this behavior is very similar to the update subscription API call. All the web hook events will be fired only after the submission of payment details by the customer and successful checkout of subscription.
Any errors related to the payment form that is submitted is handled as a response within the form so that the user is kept informed about the reason for failure to take corrective action.
curl https://{site}.chargebee.com/api/v1/hosted_pages/checkout_existing \ -u {site_api_key}:\ -d subscription[id]="__test__5SK0bLNFRFuCRrBP6" \ -d subscription[plan_id]="sub_plan1"
redirect_url
after successful checkout,
we do not recommend relying on it for completing critical post-checkout actions.
This is because redirection may not happen due to unforeseen reasons.
Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout. 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.
Note:curl https://{site}.chargebee.com/api/v1/hosted_pages/update_payment_method \ -u {site_api_key}:\ -d customer[id]="__test__5SK0bLNFRFuCV8XPz" -d card[gateway]="STRIPE"
redirect_url
after successful checkout,
we do not recommend relying on it for completing critical post-checkout actions.
This is because redirection may not happen due to unforeseen reasons.
Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout. This operation is only supported by the 2Checkout payment gateway.
curl https://{site}.chargebee.com/api/v1/hosted_pages/checkout_onetime_charge \ -u {site_api_key}:\ -d amount=1000 \ -d description="Support charge" \ -d card[gateway]="TCO" -d subscription[id]="__test__3Nl9RLTRcPq8iN4D"
This operation is only supported by the 2Checkout payment gateway.
curl https://{site}.chargebee.com/api/v1/hosted_pages/checkout_onetime_addons \ -u {site_api_key}:\ -d subscription[id]="__test__3Nl9RLTRcPq8eH3z" -d card[gateway]="TCO" -d addons[id][0]="non_recurring_addon" \ -d addons[quantity][0]=1
curl https://{site}.chargebee.com/api/v1/hosted_pages/__test__notOvqU0psFG0HAxwoePXHQJAN2ruDhG \ -u {site_api_key}: