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 challenge or a bank authorization. See confirm() for details.

Tutorials

For step-by-step integration, see the Payment Components tutorials.

Prerequisites

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

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

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);

Parameters

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"
});

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)

Parameters

Return value

Returns a PaymentComponent object.

Example

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);

Parameters

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)

Parameters

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").

Syntax

await paymentComponent.validate()

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:

• Cards: 3D Secure runs inside confirm(). If the gateway requires a challenge, Chargebee opens it for the customer to authenticate with their card issuer. Don't call the 3DS Helper alongside Payment Components.
• Bank-based methods such as iDEAL, Bancontact, Klarna, UPI, and netbanking: confirm() opens the customer's bank authorization page in a window that Chargebee manages, and waits for the result. Don't call handlePayment() or the Payment method helper yourself.

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

Syntax

await paymentComponent.confirm()

Example

async function onPayClick() {
  const isValid = await paymentComponent.validate();
  if (!isValid) {
    // validate() has surfaced inline errors in the form
    return;
  }
  await paymentComponent.confirm();
}

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()

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)

Parameters

Return value

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

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.

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.";
    },
  },
);

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.

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

Creates a PaymentButtonComponent object.

Syntax

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

Parameters

Return value

Returns a PaymentButtonComponent object.

Example

mount(target)

Inserts the payment button component into the DOM.

Syntax

await paymentButtonComponent.mount(target);

Parameters

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)

Parameters

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()

Return value

None.

PaymentIntent object

The payment_intent API object is provided below for reference.

Payment methods

The following table lists the supported payment methods:

Localization

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