ChargebeeAPI

Checkout charge-items and one-time charges

Idempotency Supported
Try in API Explorer

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:

  1. Call this endpoint, providing item prices, charges, coupons and a host of other details such as billing and shipping addresses of the customer, to be prefilled 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.
  2. Send the customer to the Checkout url received in the response.
  3. Once they complete checkout, the set of charge-items 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.

Customer resource lookup and creation

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.

Multiple business entities

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.

Sample Request

URL Format

POST https://[site].chargebee.com/api/v2/hosted_pages/checkout_one_time_for_items

Input Parameters

business_entity_id
optional, string, max chars=50

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.

Note

An alternative way of passing this parameter is by means of a custom HTTP header.

See also

Customer resource lookup and creation.
layout
optional, enumerated string

Specifies the checkout layout that overrides the default checkout layout configured in the Checkout & Self-Serve Portal settings.

Possible Enum Values
in_app

Indicates in-app checkout version

full_page

Indicates full page checkout version

invoice_note
optional, string, max chars=2000

A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.

coupon_ids
optional, string, max chars=100

List of Coupons to be added.

currency_code
required if Multicurrency is enabled, string, max chars=3

The currency code (ISO 4217 format) of the invoice amount.

redirect_url
optional, string, max chars=250

The customers will be redirected to this URL upon successful checkout. The hosted page id and state will be passed as parameters to this URL.

Note :

  • Although the customer will be redirected to the 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 configured in Settings > Hosted Pages Settings would be overriden by this redirect URL.
  • Eg : http://yoursite.com?id=**&state=succeeded
  • This parameter is not applicable for iframe messaging.
cancel_url
optional, string, max chars=250

The customers will be redirected to this URL upon canceling checkout. The hosted page id and state will be passed as parameters to this URL.

Note : - Cancel URL configured in Settings > Hosted Pages Settings would be overriden by this cancel URL.
Eg : http://yoursite.com?id=&state=cancelled

  • This parameter is not applicable for iframe messaging and in-app checkout.
pass_thru_content
optional, string, max chars=2048

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.

customer[0..n]
Parameters for customer
pass parameters as customer[<param name>]
invoice[0..n]
Parameters for invoice
pass parameters as invoice[<param name>]
card[0..n]
Parameters for card
pass parameters as card[<param name>]
billing_address[0..n]
Parameters for billing_address
pass parameters as billing_address[<param name>]
shipping_address[0..n]
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
item_prices[0..n]
Parameters for item_prices. Multiple item_prices can be passed by specifying unique indices.
pass parameters as item_prices[<param name>][<idx:0..n>]
item_tiers[0..n]
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
charges[0..n]
Parameters for charges. Multiple charges can be passed by specifying unique indices.
pass parameters as charges[<param name>][<idx:0..n>]
discounts[0..n]
Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]
entity_identifiers[0..n]
Parameters for entity_identifiers. Multiple entity_identifiers can be passed by specifying unique indices.
pass parameters as entity_identifiers[<param name>][<idx:0..n>]

Returns

hosted_pageHosted page object
Resource object representing hosted_page