Frontend Capabilities

# Payment Components

Early Access

Payment Components is an early access feature. Chargebee is not accepting new enablement requests at this time. Availability updates will be announced in the Chargebee Release Notes (opens new window).

# Overview

This page documents the Payment Components API, which allows you to integrate secure, customizable payment forms directly into your website. Payment Components provide a complete payment collection solution with built-in support for multiple payment methods, localization, and styling options.

# Prerequisites

Before using the Payment Components API, ensure you have initialized Chargebee.js in your application with a publishable key (opens new window).

const chargebee = Chargebee.init({
  site: "YOUR_CHARGEBEE_BILLING_SUBDOMAIN",
  publishableKey: "test__" // Your publishable API key
});
1
2
3
4

# Components object

The Components object is used to create and manage instances of UI components for securely collecting sensitive payment information from your customers.

# components(options)

Creates a Components object and sets the default styling and localization options to be applied to the components created using this object.

# Syntax

chargebee.components(options);
1

# Parameters

options
Object Required View properties

# Return value

Returns a Components instance.

# Example

const components = chargebee.components({
    style: {
        theme: {
            radius: "large",
            scaling: "100%",
        },
        variables: {
            colorBackground: "#dcf5bf33",
            defaultFontFamily: "'Sora', sans-serif",
        },
        rules: {
            ".g-RadioCardsItem": {
                background: "linear-gradient(150deg, transparent 60%, var(--gray-9))",
            },
            ".g-BaseButton:where(.g-variant-solid)": {
                background: "linear-gradient(10deg, var(--gray-9), var(--gray-7))",
                boxShadow: "0 6px 8px rgba(0, 0, 0, 0.3), 0 3px 6px rgba(0, 0, 0, 0.2)",
            },
            "#payment-container": {
                padding: "var(--space-6)",
                minHeight: "150rem",
            },
        },
    },
    locale: "fr"
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# PaymentComponent object

The PaymentComponent is a UI component used to collect payment information from your customers.

# create('payment', options, callbacks)

Creates a PaymentComponent object.

# Syntax

components.create('payment', options, callbacks)
1

# Parameters

componentType
string Required
Allowed Values:
payment
options
Object Required View properties
callbacks
Object View properties

# Return value

Returns a PaymentComponent object.

# Example

DETAILS 
const paymentComponent = components.create(
  "payment",
  {
    style: {
      theme: {},
      variables: {},
      rules: {},
    },
    locale: "en",
    layout: {
      type: "tab",
      showRadioButtons: true,
      defaultItemsToShow: 2,
    },
    paymentMethods: { 
      sortOrder: ["card"],
      savePaymentMethod: {
          label: "Save this to your list of payment methods",
          consentType: "consent",
          description: "I authorize Chargebee to save this payment method and automatically charge this payment method for any further transactions associated with it.",
          defaultChecked: false
      }
    },
    paymentIntent: { id: paymentIntent.id },
    form: {
      customer: {
        firstName: {
          required: true,
        },
        lastName: "default",
      },
      shippingAddress: {
        firstName: {
          placeholder: "Custom Placeholder",
        },
        addressLine1: {
          short: true,
        },
        countryCode: {
          order: 3,
        },
        zip: "default"
      },
    },
    context: {
      cart: {
        lineItems: [{ id: "1234", type: "plan" }],
      },
      customer: {
        firstName: "john",
        lastName: "doe",
      },
    },
  },
  {
    onAppReady() {
      // Payment Component is connected; safe to call paymentComponent SDK methods.
      console.log("Payment Component connected");
    },
    onError(error) {
      console.log(error);
    },
    onSuccess(PaymentIntent, extra) {
      console.log(PaymentIntent, extra);
    },
    onPaymentMethodChange(paymentMethod) {
      console.log(paymentMethod);
    },
    onButtonClick(){
      // if validation is failure
      // return Promise.reject('validation_failure')
      return Promise.resolve();
    },
    onClose() {
      console.log("Payment Component closed");
    }
  },
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# mount(target)

Inserts the payment UI component into the DOM.

Success means the Payment Component is attached to your page and ready to send and receive SDK calls. It does not wait for the payment-method list to load or for form fields to render; for that, listen for onPaymentMethodChange.

# Syntax

await paymentComponent.mount(target);
1

# Parameters

target
string | HTMLElement Required
DOM element or a CSS selector where the component should be mounted.

# Return value

Returns a promise that resolves to true if the component mounts successfully, or false if an error occurs.

# update(options)

Updates the Payment Component options using a shallow merge and remounts the component.

Success means the Payment Component is ready to send and receive SDK calls. It does not wait for the payment-method list to load or for form fields to render; for that, listen for onPaymentMethodChange.

# Syntax

paymentComponent.update(options)
1

# Parameters

options
Object View properties

# Return value

None.

# validate()

Runs validation on the currently selected payment method's form and returns whether it is ready to be confirmed. As a side effect, any field-level errors are surfaced inline within the Payment Component (for example, "Card number is invalid", "Expiry is required").

Call `validate()` first when using a custom button

confirm() does not validate the form before submitting. If you are driving the payment flow from your own custom Pay button (rather than using the PaymentButtonComponent), you must call await paymentComponent.validate() and only proceed when it resolves to true. The built-in PaymentButtonComponent validates the form internally before calling confirm(), so you do not need to do this yourself when using it.

# Syntax

await paymentComponent.validate()
1

# Return value

A promise that resolves to a boolean:

  • true — every required field on the active payment method is filled in and passes validation. Safe to call confirm().
  • false — one or more fields are missing or invalid (errors are now visible to the user).

# confirm()

Initiates the payment authorization process for the currently selected payment method. After the user completes the payment, the function triggers the onSuccess() callback with the authorized paymentIntent. If anything goes wrong during authorization, the onError() callback fires instead.

Call `validate()` first when using a custom button

confirm() does not validate the form before submitting. If you are driving the payment flow from your own custom Pay button (rather than using the PaymentButtonComponent), you must call await paymentComponent.validate() and only proceed when it resolves to true. The built-in PaymentButtonComponent validates the form internally before calling confirm(), so you do not need to do this yourself when using it.

# Syntax

await paymentComponent.confirm()
1

# Example

async function onPayClick() {
  const isValid = await paymentComponent.validate();
  if (!isValid) {
    // validate() has surfaced inline errors in the form
    return;
  }
  await paymentComponent.confirm();
}
1
2
3
4
5
6
7
8

# Return value

None. Authorization results are delivered via the onSuccess() and onError() callbacks.

# close()

Removes the mounted component from the DOM and triggers the onClose() callback of the Payment Component if defined.

# Syntax

paymentComponent.close()
1

# Return value

None.

# PaymentButtonComponent object

The PaymentButtonComponent is a prebuilt UI button that submits the payment form when clicked. The button dynamically updates based on the selected payment method.

Optional component

The payment button component is optional. You can implement your own custom button. However, even if you choose not to use Chargebee's payment button component, Chargebee still renders payment buttons for all wallet-based payment methods that the user selects.

# create('payment-button', options, callbacks)

Creates a PaymentButtonComponent object.

# Syntax

components.create('payment-button', options, callbacks)
1

# Parameters

componentType
string Required
Allowed Values:
payment-button
options
Object Required View properties
callbacks
Object View properties

# Return value

Returns a PaymentButtonComponent object.

# Example

DETAILS 
const paymentButtonComponent = components.create(
  "payment-button",
  {
    style: {
      theme: {},
      variables: {},
      rules: {},
    },
    locale: "en",
    paymentMethods: {
      options: {
        card: {
          text: "Pay",
        },
        google_pay: {
          buttonSizeMode: "fill",
        },
      },
    },
  },
  {
    onError(error) => {
      console.log(error);
    },
    onClose() {
      console.log("payment button component closed");
    },
  },
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# mount(target)

Inserts the payment button component into the DOM.

# Syntax

await paymentButtonComponent.mount(target);
1

# Parameters

target
string | HTMLElement Required
DOM element or a CSS selector where the component should be mounted.

# Return value

Returns a promise that resolves to true if the component mounts successfully, or false if an error occurs.

# update(options)

Updates the payment button component options using a shallow merge and remounts the button.

# Syntax

paymentButtonComponent.update(options)
1

# Parameters

options
Object View properties

# Return value

None.

# close()

Removes the mounted payment button component from the DOM and triggers the onClose() callback of the payment button component if defined.

# Syntax

paymentButtonComponent.close()
1

# Return value

None.

# PaymentIntent object

The payment_intent API object (opens new window) is provided below for reference.

DETAILS
id
string Required
status
string
Allowed Values:
consumed
in_progress
inited
expired
authorized
amount
number
gateway_account_id
string
expires_at
number
payment_method_type
string
Allowed Values:
google_pay
apple_pay
paypal_express_checkout
venmo
card
bancontact
ideal
upi
netbanking_emandates
klarna_pay_now
online_banking_poland
direct_debit
amazon_payments
pay_to
faster_payments
sepa_instant_transfer
created_at
Unix timestamp
modified_at
Unix timestamp
updated_at
Unix timestamp
currency_code
string
object
string
gateway
string

# Payment methods

The following table lists the supported payment methods:

Supported payment methods
card
google_pay
apple_pay
paypal_express_checkout
venmo
bancontact
ideal
upi
netbanking_emandates
klarna_pay_now
online_banking_poland
direct_debit
amazon_payments
pay_to
faster_payments
sepa_instant_transfer

# Localization

Payment Components support multiple locales, as shown in the following table:

Code Language
es Spanish
en English
fr French
de German
it Italian
pt Portuguese

Override default translations

You can customize the translated text on the Payment Components UI using the Chargebee Billing Language Pack.

← Pricing Table Object ✨ →