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/"
}
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:
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 the ID provided, 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.
# Creates a checkout with non-recurring addon for a customer. curl https://{site}.chargebee.com/api/v2/hosted_pages/checkout_one_time_for_items \ -u {site_api_key}:\ -d customer[id]="__test__XpbXKKYSOUtL5p2E" -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" -d item_prices[item_price_id][0]="ssl-charge-USD" \ -d item_prices[unit_price][0]=2000
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.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:
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 the ID provided 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.
# checkout a new subscription for items curl https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new_for_items \ -u {site_api_key}:\ -d subscription_items[item_price_id][0]="basic-USD" \ -d subscription_items[quantity][0]=1 \ -d subscription_items[item_price_id][1]="day-pass-USD" \ -d subscription_items[unit_price][1]=100
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.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:
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. curl https://{site}.chargebee.com/api/v2/hosted_pages/checkout_existing_for_items \ -u {site_api_key}:\ -d subscription[id]="__test__KyVnGWS4EgP3HA" -d subscription_items[item_price_id][0]="basic-USD" \ -d subscription_items[quantity][0]=4 \ -d subscription_items[unit_price][0]=1000
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.true
will have the subscription reset its term to the current date (provided end_of_term
is false).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.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: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"
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.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/accept_quote \ -u {site_api_key}:\ -d quote[id]="1"
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.curl https://{site}.chargebee.com/api/v2/hosted_pages/extend_subscription \ -u {site_api_key}:\ -d billing_cycle=2 \ -d expiry=14 \ -d subscription[id]="__test__KyVnHhSBWmIgw2u6"
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
# Checkout Gift subscription for Items curl https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift_for_items \ -u {site_api_key}:\ -d gifter[customer_id]="gifter" -d subscription_items[item_price_id][0]="gift-plan-USD" \ -d subscription_items[quantity][0]=2
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.curl https://{site}.chargebee.com/api/v2/hosted_pages/claim_gift \ -u {site_api_key}:\ -d gift[id]="__test__KyVnHhSBWmGdM2tv__test__21cdZvclBhOULyCT1SBUPDKjoXsuc3wdj"
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.
curl https://{site}.chargebee.com/api/v2/hosted_pages/retrieve_agreement_pdf \ -u {site_api_key}:\ -d payment_source_id="pm___test__KyVnHhSBWmKRg2uT"
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 |
|
curl https://{site}.chargebee.com/api/v2/hosted_pages/__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r \ -u {site_api_key}:
This API retrieves the list of hosted page resources.
curl https://{site}.chargebee.com/api/v2/hosted_pages \ -G \ -u {site_api_key}:\ --data-urlencode limit=2
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.curl https://{site}.chargebee.com/api/v2/hosted_pages/pre_cancel \ -u {site_api_key}:\ -d pass_thru_content="{custom : {discount_percent: 10}}" \ -d subscription[id]="__test__KyVnHhSBWmCoF2tJ"
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
.
curl https://{site}.chargebee.com/api/v2/hosted_pages/events \ -u {site_api_key}:\ -d event_name="CANCELLATION_PAGE_LOADED" \ -d occurred_at=1435054328 \ -d event_data="{subscription_id : '__test__KyVnHhSBWmCoF2tJ'}"
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.curl https://{site}.chargebee.com/api/v2/hosted_pages/view_voucher \ -u {site_api_key}:\ -d customer[locale]="fr-CA"