Frontend Capabilities

# Payment Components ✨

Early Access

The Payment Components feature is in early access. To request access, submit a request (opens new window) via Chargebee Billing.

# 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",
      },
    },
  },
  {
    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

# mount(target)

Inserts the payment UI component into the DOM.

# 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.

# Syntax

paymentComponent.update(options)
1

# Parameters

options
Object View properties

# Return value

None.

# validate()

Verifies that the submitted payment details are valid and ready for processing.

# Syntax

await paymentComponent.validate()
1

# Return value

A promise that resolves to true when the payment button is properly configured and in a valid state, or false when validation requirements are not met.

# confirm()

Initiates the payment authorization process. After the user completes the payment, the function calls the onSuccess() callback with the authorized paymentIntent.

# Syntax

await paymentComponent.confirm()
1

# Return value

None.

# 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 ✨ →