Payment Components

Payment Components are prebuilt UI elements that provide input fields and buttons for securely collecting payment information from your customers. Payment Components support multiple payment methods in a single integration.

Use Payment Components when you build your own checkout experience but want to offload payment handling to Chargebee.

Note

Payment Components supersede the following Chargebee.js features:

For what changes when you move across, see Comparison with Card Components and the Payment method helper.

Where Payment Components fit

Payment Components are one of several ways to collect a payment through Chargebee. Which one you choose depends on how much of the checkout you want to build yourself.

A typical checkout moves through the following stages:

Payment Components handle the highlighted Payment stage. You own every other stage, including the cart, the pricing, and what happens after the payment succeeds.

Choose Payment Components when you build your own checkout UI and want Chargebee to collect the payment securely within it. You control the layout, the styling, and the surrounding page, while Chargebee handles the payment methods, gateway routing, PCI scope, and customer authentication.

Choose Chargebee's hosted Checkout when you want Chargebee to run the cart, pricing, tax, and payment together on a page that Chargebee hosts and maintains. This is the fastest route to a working flow because there is no checkout UI to build. See Integration options for the ways to open the hosted page.

Comparison with Card Components and the Payment method helper

Before Payment Components, collecting a payment through Chargebee.js meant picking a module for each payment method: Card Components for cards, and the Payment method helper for everything else. Payment Components replace both with a single integration.

Area of work	Card Components and Payment method helper	Payment Components
Adding a payment method	Every method needs its own integration work: Card Components for cards, a handler you load for each wallet, and method-specific options within the shared flow for bank-based methods.	One integration covers every supported method. The component fetches the methods your site is eligible for, so methods you enable later need little or no new code.
Gateway differences	You handle what each gateway expects, including loading its SDK, running 3D Secure and non-3D Secure card flows, tokenization, setup intents, and redirect or QR code authorization.	Payment Components load the gateway SDK and run these flows inside the component.
Payment UI	You build and maintain the payment UI for every method.	Chargebee provides and maintains the UI, within the layout and styling you set in Payment Components.
Validation and error handling	Each handler surfaces its own validation and errors.	One lifecycle covers every method: `validate()`, `confirm()`, and the `onSuccess` and `onError` callbacks.
Ongoing maintenance	Gateway and payment method changes can require changes in your code, and that work grows with every method and gateway you add.	Most gateway and payment method changes land inside Payment Components, so your integration stays as it is.
PCI scope	Card Components collect card details in an iframe hosted on Chargebee's domain, so card data never reaches your servers.	The same. Payment Components collect card details in a Chargebee-hosted iframe, so moving across doesn't change your PCI scope.
Supported payment methods	Includes a few gateway and payment method combinations that Payment Components don't cover yet.	Covers the methods listed in Supported payment methods. Payment Components need a `payment_intent` to collect a payment, so combinations without payment intent support stay on the older path until they have it.

Key benefits

Simple integration: Integrate just once to support multiple payment methods across various payment gateways. This helps you expand globally and increase revenue, without additional development cost.
PCI compliant: Payment Components handle card data within an iframe hosted on Chargebee's domain, so your servers never process or store your customers' payment information. This reduces your PCI compliance requirements significantly.
Advanced routing support: Route payments through specific gateways based on rules defined in Chargebee Billing. If you have multiple payment gateways configured, Advanced Routing lets you optimize payment flow for better reliability, cost-efficiency, and regional coverage.
Customizable UI and branding: Tailor the user interface, layout, and styling to match your website's design, creating a branded payment experience that reduces friction and increases conversion.
Responsive: Payment Components are responsive across devices and screen sizes.
Payment submission button: Includes an optional prebuilt button that securely processes payments. You can place it anywhere in the UI layout and it adapts to the selected payment method.
Additional form fields: Add extra form fields to collect more information during payment collection.
Multi-language support: Support translations in multiple languages using the locale option. You can customize the translated text using the Chargebee Billing Language Pack.
Lifecycle callbacks: Payment Components expose callbacks for ready, method change, button click, success, and error, so you can hook validation, analytics, and tax updates into the payment flow. See the API reference.

How Payment Components work

On the page, a Payment Component looks self-contained, but it sits in the middle of an exchange between your page, your backend, Chargebee, and your payment gateway. The following diagram traces that exchange end to end.

If authorization fails at any point, the Payment Component calls onError() instead of onSuccess(), and the customer can correct the details and try again.

Note the following about the participants:

Your page never touches payment details. It creates and mounts the components, then reacts to their callbacks.
Chargebee.js is the library you load from https://js.chargebee.com/v2/chargebee.js. It creates the components and loads them from Chargebee's domain.
The Payment Component renders the payment methods and collects the details inside an <iframe> hosted on Chargebee's domain, which is what keeps the data out of your PCI scope.
The Payment Button Component is optional. If you omit it, use your own button and call validate() and confirm() yourself.
Your backend holds your full-access API key. It creates the payment_intent and, after authorization, creates the subscription.
The payment gateway is where Chargebee sends the payment. When a card needs 3D Secure or a bank payment needs authorization, the gateway returns a URL and Chargebee opens it for the customer.

For the code behind each step, see the quickstart code walkthrough.

Get started with Payment Components

Download a sample app and refer to its code walkthrough to implement Payment Components.

Business use cases for Payment Components

Payment Components can be customized to suit different business needs, such as varying the payment methods on offer by cart value or by the customer's region, styling the component to match your website design, and localizing its field and label text.

Supported payment methods

Payment Components currently support the following payment methods.

Cards

Payment Components support card payments.

Warning

Among the gateways that support non-3D Secure payment flows, the following are not yet supported: Authorize.net, Sage Pay, Vantiv, and all gateways integrated via Spreedly.

3D Secure and SCA

Payment Components handle 3D Secure (3DS) authentication for you. When you call confirm(), or when the customer clicks the built-in Payment Button Component, the component performs the following steps:

Sends the payment to your gateway.
If the gateway requires 3DS, opens the challenge for the customer to authenticate with their card issuer.
Moves the payment_intent status from inited through in_progress to authorized.
Calls your onSuccess() callback with the authorized payment_intent, or onError() if authentication or authorization fails.

Warning

Chargebee.js also provides a separate 3DS Helper module with functions such as load3DSHandler() and handleCardPayment(). That module is for other integration styles, including the Card component, gateway hosted fields, permanent tokens, and raw card details. Payment Components run 3DS internally, so don't call the 3DS Helper alongside them.

To try the challenge flow yourself, see Test the 3D Secure challenge.

Direct Debit

Payment Components support every direct debit payment method except ACH via QuickBooks Payments.

ACH is supported for Chargebee-supported ACH gateways, including Authorize.Net, GoCardless, CyberSource, Chargebee Payments, BlueSnap, Braintree, Adyen, Vantiv, Checkout.com, and Stripe.

Wallets

When using wallets, the customer authenticates with the wallet provider. Payment Components handle those redirects internally. Payment Components support the following wallets:

Apple Pay: Supported via Adyen, Checkout.com, Braintree, and Stripe gateways.
Google Pay: Supported via Adyen, BlueSnap, Braintree, and Stripe gateways.
PayPal: Supported via Adyen, Braintree, and PayPal gateways.
Venmo: Supported only via the Braintree gateway.
Amazon Payments: Supported only via the Amazon Pay gateway.

Bank-based payments

When using bank-based methods, the customer authenticates with their bank. Payment Components handle those redirects internally. Payment Components support the following bank-based methods:

iDEAL: Supported via Adyen, Mollie, and Stripe gateways.
Bancontact: Supported via Adyen, Checkout.com, Mollie, and Stripe gateways.
Klarna Pay Now: Supported via the Adyen gateway.
UPI: Supported via the Razorpay gateway.
Netbanking E-Mandates (India): Supported via the Razorpay gateway.
Online Banking Poland: Supported via the Adyen gateway.

Open banking

Note

Open banking support in Payment Components is in private beta.

Payment Components support the following payment methods through open banking via GoCardless:

PayTo
SEPA Instant Transfer
Faster Payments

Offline payment methods

Payment Components support these offline payment methods:

Cash
Check
Bank Transfer

Limitations

Adding an info icon or tooltip next to the card CVV field is not supported.
Loading custom font files is not supported. You can still set font family names through the styling API. They are loaded only when the fonts are available on the customer's device.
Because Payment Components run inside a cross-origin iframe, parent pages cannot receive per-keystroke or field-change events from inside Payment Components. Use callbacks such as onPaymentMethodChange, onButtonClick, onSuccess, and onError for analytics instead. See Track typing or field changes in Payment Components.

Troubleshoot Payment Components

See Payment Components troubleshooting if Payment Components fail to load or wallet buttons do not render.