Chargebee.js

# Payment Components

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

Payment Components also authenticate the customer for you during confirmation, whether that means a card 3D Secure (opens new window) challenge or a bank authorization. See confirm() for details.

# Tutorials

For step-by-step integration, see the Payment Components tutorials (opens new window).

# 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",
    channel: "desktop",
    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
79

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

This one call also authenticates the customer when the payment requires it. The authentication path depends on the payment method, but your code is the same in both cases:

Either way, confirm() resolves without a value. The onSuccess() callback fires once the payment_intent reaches the authorized status, and onError() fires otherwise.

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.

# onError() callback

Called when an error occurs while the Payment Component renders, or at any point during the payment flow. Pass this function in the callbacks object of create('payment', options, callbacks).

The component calls this function before it displays anything, and the value you return determines the message that the component then shows inside its iframe.

# Syntax

onError(error)
1

# Parameters

error
Object Hide properties
code
string
Identifies the error. Chargebee derives it from the error's name or its error_code, and falls back to UNKNOWN_CODE.
message
string
Describes the error in a form you can show to the customer. This is the text the payment component displays by default.
paymentMethod
string
The payment method that the error came from, such as card. The possible values are the same as PaymentIntent.payment_method_type.
error
Unknown
The original error that Chargebee received, for logging and debugging.

# Return value

The component reads the returned value synchronously to decide what to show inside its iframe:

Return value Message shown inside the component
string Your text, unless the error has a translated message.
false No message. Use this when your page reports the error in its own UI.
Nothing Chargebee's default message, which is the error.message value.

Translated messages take precedence over the string you return. When Chargebee maps the error to a known cause and the current locale has a translation for that cause, the component shows the translated message and ignores your string. To suppress the message for every error, including errors that have a translation, return false.

A promise counts as returning nothing, because the component doesn't wait for it to settle. The message clears itself after a few seconds.

For more information, see Customize the error message shown inside Payment Components (opens new window).

# Example

const paymentComponent = components.create(
  "payment",
  { paymentIntent: { id: paymentIntent.id } },
  {
    onError(error) {
      console.log(error.code, error.message);
      return "We couldn't process your payment. Try again or use another payment method.";
    },
  },
);
1
2
3
4
5
6
7
8
9
10

# 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 (opens new window) 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 (opens new window).

← Pricing Table Object →