Hosted pages are the easiest way to integrate Chargebee with your website. For card payment methods, they help meet most of your PCI DSS compliance requirements. Chargebee offers hosted pages where your customers can perform the following actions:
redirect_url
with the hosted page id
and state
passed as query string parameters. As soon as the redirection happens, retrieve the hosted page to get details of the customer, subscription, invoice etc.
{
"created_at": 1517464663,
"embed": false,
"expires_at": 1517468263,
"id": "__one_time_checkout___test__cdqM9MLUubELMycut0Cr9sHq8gOTKEZSdcu",
"object": "hosted_page",
"resource_version": 1517444863979,
"state": "created",
"type": "checkout_one_time",
"updated_at": 1517444863,
"url": "https://yourapp.chargebee.com/pages/v3/__one_time_checkout___test__cdqM9MLUubELMycut0Cr9sHq8gOTKEZSdcu/"
}
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.
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:
checkout_new
, checkout_existing
, and checkout_one_time
, the URL expires 3 hours after the page is created.collect_now
and manage_payment_sources
, the URL expires 5 days after creation.Create a Chargebee hosted page to accept payment details from a customer and checkout charge-items and one-time charges.
The following steps describe how best to use this API:
pass_thru_content
containing information and IDs from your systems that must be associated with the checkout page. url
received in the response.customer
record in Chargebee, and they are redirected to the redirect_url
with the id
and state
attributes passed as query string parameters. When customer[id]
is provided for this operation, it is looked up by Chargebee, and if found, the hosted_page is created for it. If not found, a new customer resource is created with an autogenarated ID, and the hosted_page is created.
If multiple business entities are created for the site, the customer resource lookup and creation happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context , and if not found, the resource is created for the default business entity of the site.
Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.
An alternative way of passing this parameter is by means of a custom HTTP header.
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 such as user closing the tab, or exiting the browser, and so on. If there is any synchronization that you are doing after the redirection, you will have to have a backup. Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout. 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.
Create a Chargebee hosted page to accept payment details from a customer and checkout a new subscription.
The following steps describe how best to use this API:
Call this endpoint, providing item prices, coupons and a host of other details such as billing and shipping addresses to be prefilled for the customer on the checkout page. You may also provide pass_thru_content
containing information and IDs from your systems that must be associated with the checkout page.
The first item price in the list (parameter subscription_items[item_price_id][0]
) must be an item_price
of item_type plan
.
url
received in the response. redirect_url
with the id
and state
attributes passed as query string parameters.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. When the customer[id]
parameter is provided and if a customer resource with the ID is found to be already created in Chargebee, the subscription is created under that customer resource. If not found, then a new customer resource is created with an autogenarated ID and the subscription is created under it.
If multiple business entities are created for the site, the customer resource lookup and creation happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context, and if not found, the resource is created for the default business entity of the site.
Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.
An alternative way of passing this parameter is by means of a custom HTTP header.
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 such as user closing the tab, or exiting the browser, and so on. If there is any synchronization that you are doing after the redirection, you will have to have a backup. Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout. 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.
Create a Chargebee hosted page to accept payment details from a customer and checkout to update the subscription.
The following steps describe how best to use this API:
Provide item prices, coupons and a host of other details such as billing and shipping addresses to be prefilled for the customer on the checkout page. You may also provide pass_thru_content
containing information and IDs from your systems that must be associated with the checkout page.
The first item price in the list (parameter subscription_items[item_price_id][0]
) must be an item_price
of item_type plan
.
url
received in the response. They can now add a payment method or use an existing one, to complete the checkout. redirect_url
with the id
and state
attributes passed as query string parameters.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. create_pending_invoices
is set to true
, and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date
. When passing this parameter, the following prerequisites must be met:
invoice_date
must be in the past.invoice_date
is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.changes_scheduled_at
, reactivate_from
, or trial_end
.invoice_immediately
is true
.terms_to_charge
is inclusive of this new term. See description for the force_term_reset
parameter to learn more about when a subscription term is reset. status
is cancelled
and it is being reactivated via this operation, this is the date/time at which the subscription should be reactivated.changed_scheduled_at
. reactivate_from
can be backdated (set to a value in the past). Use backdating when the subscription has been reactivated already but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:
changes_scheduled_at
cannot be earlier than 14th February.cancelled
subscriptions. When set to true
, it activates the canceled subscription; otherwise, subscription changes are applied without altering its status
. Additionally, if not explicitly set and the subscription_items
provided in the API differ from the existing items, the subscription will still be reactivated. Note: This parameter is relevant only for subscriptions with status
of active
, non_renewing
, or cancelled
.
When you set this parameter to true
, the subscription term resets to the date of the subscription change.
By default, if you change the plan-item price to another with the same billing period, the subscription term remains unchanged. For example, if the subscription renews on the 28th of every month, it will continue to renew on the 28th after the change.
Note: If the new plan-item price has a different billing period from the current plan-item price, the subscription term resets automatically, regardless of the value of force_term_reset
.
change_option
is set to specific_date
, specify the date and time for the subscription change to occur or to reflect a past change. reactivate_from
. changes_scheduled_at
value cannot be set to a past date.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 such as user closing the tab, or exiting the browser, and so on. If there is any synchronization that you are doing after the redirection, you will have to have a backup. Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout. 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.
Note: If you're using In-App Checkout , 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.
Note: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 such as user closing the tab, or exiting the browser, and so on. If there is any synchronization that you are doing after the redirection, you will have to have a backup. Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout. 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 session, 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.
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 such as user closing the tab, or exiting the browser, and so on. If there is any synchronization that you are doing after the redirection, you will have to have a backup. Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout.Creates a hosted page for a customer (called the gifter) to gift a subscription to another customer (called the receiver).
When gifter[customer_id]
is provided, it is looked up in Chargebee when the gifter completes the hosted page checkout. If not found, a new customer resource is created with this ID.
If multiple business entities are created for the site, the lookup and creation of the gifter customer resource happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context, and if not found, the resource is created for the default business entity of the site.
Once the gifter checks out using the hosted page returned by this endpoint, Chargebee checks if a customer resource with the receiver’s email address exists. The first such customer record is considered the receiver’s customer resource. A new customer resource is created for the receiver if none are found.
If multiple business entities are created for the site, the lookup and creation of the gift receiver’s customer resource happen within the context of the business entity of the gifter
Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.
An alternative way of passing this parameter is by means of a custom HTTP header.
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 such as user closing the tab, or exiting the browser, and so on. If there is any synchronization that you are doing after the redirection, you will have to have a backup. Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout.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 such as user closing the tab, or exiting the browser, and so on. If there is any synchronization that you are doing after the redirection, you will have to have a backup. Chargebee recommends listening to appropriate webhooks such as subscription_created
or invoice_generated
to verify a successful checkout.This is applicable only for Direct Debit via SEPA, Bacs, Bg Autogiro, BECS (for both Australia and New Zealand) and PAD. For Direct Debit, the customer needs to accept an agreement that allows the merchant to debit their bank account. This agreement PDF allows you to easily display scheme-rules compliant Direct Debit mandates to your customers.
This API retrieves the redirect link to the corresponding agreement for customers. The agreement PDF can be your “Thank You” page or sent by email to customers. Communicating this PDF to your customers is mandatory.
Customer locale is used to generate the PDF in the required language. If a customer language is not supported, the PDF is generated in English. Checkout the list of languages supported by GoCardless.
state
is automatically changed to succeeded
. Acknowledging a hosted page confirms that you have moved the customer details from Chargebee into your system and are ready to fulfill it. This API is used to acknowledge the hosted page in succeeded
state and change its state to acknowledged
. When you retrieve a hosted page whose status
is successful
, the content
attribute has the following objects based on the type
of the hosted page.
type of hosted page |
content attribute constituents |
checkout_new |
|
checkout_existing |
|
update_payment_method |
|
pre_cancel |
retention : Use the bypass flag in this object to route the cancellation flow to the merchants’ portal or the Chargebee Retention.
beta . To enable Retention, Contact Support.
|
collect_now |
|
This API retrieves the list of hosted page resources.
hosted_page
resource of type
pre_cancel
. Route canceling users to this page to provide them a retention experience and start saving revenue.url
in the endpoint response.Additional data to be passed to Chargebee Retention. Only the value of pass_thru_content.custom
is sent to Chargebee Retention. It is sent as the value of the custom
property. The fields provided in pass_thru_content.custom
must be preconfigured in Chargebee Retention.
Although only pass_thru_content.custom
is sent to Chargebee Retention, all of pass_thru_content
is stored by Chargebee billing and is retrievable as an attribute of the hosted_page
.
hosted_page
resource of type, view_voucher
. When your end customers choose the Boleto payment method, you can generate a voucher for their pending invoice. Using this API, you can create a voucher_detail hosted page for your customers and email them a link to this hosted page. Your customers can review the voucher details on the page by clicking the link in the email.