# Card Components
Use Payment Components
The Payment Components solution offers enhanced features and an improved user experience compared to the Card Component. We encourage you to use Payment Components to take full advantage of these improvements.
# Overview
This page documents the Card Components API, which allows you to create secure, card input fields integrated with Chargebee. Card components can be integrated with or without 3D Secure (3DS) authentication. The components provide a secure way to collect payment card information directly on your website.
# Prerequisites
- Ensure that your payment gateway is supported by Card Components. See the list of supported gateways.
- Ensure you have initialized Chargebee.js in your application with a publishable key (opens new window).
var cbInstance = Chargebee.init({
site: "YOUR_CHARGEBEE_BILLING_SUBDOMAIN", // Your test site. This is the subdomain of your Chargebee Billing site.
domain: "https://mybilling.acme.com" // This is your custom domain, if configured in Chargebee. Chargebee-hosted pages will be served from this domain.
publishableKey: "test__"
})
2
3
4
5
# Load the components module
# load() deprecated
Loads the specified Chargebee module. This function must be called before using any card component functionality.
Important
All card component and field functionality can be used only after the components module is loaded. If you are using Chargebee wrappers, the module loading is handled automatically. Otherwise, ensure you register components after the promise resolves.
# Syntax
chargebee.load(moduleName);
# Parameters
DETAILS
components
3ds-handler
functions
ideal
sofort
google-pay
bancontact
giropay
dotpay
paypal
netbanking_emandates
apple-pay
upi
payconiq_by_bancontact
venmo
# Return value
Returns a promise that resolves after the corresponding module has been loaded.
# Example
// Load the components module before creating card components.
chargebee.load('components').then(() => {
console.log('Components module loaded successfully.');
// Now you can create and mount card components.
const cardComponent = chargebee.createComponent('card');
cardComponent.mount('#card-component');
}).catch((error) => {
console.error('Failed to load components module:', error);
});
2
3
4
5
6
7
8
9
# Create a card component
# createComponent()
Creates a card component based on the specified componentType and configuration options.
# Syntax
chargebee.createComponent(componentType, options)
# Parameters
DETAILS
card
# Return value
Returns a Card component object that provides methods to manage the card component.
# Example
DETAILS
const cardComponent = chargebee.createComponent("card", {
placeholder: {
number: "Number",
expiry: "Expiry",
cvv: "CVV",
},
classes: {
focus: 'focus',
invalid: 'invalid',
empty: 'empty',
complete: 'complete',
},
style: {
// override styles for default state
base: {
color: '#333',
fontWeight: '500',
fontFamily: 'Lato, BlinkMacSystemFont, Segoe UI, Helvetica Neue, sans-serif',
fontSize: '16px',
fontSmoothing: 'antialiased',
':focus': {
color: '#424770',
},
'::placeholder': {
color: 'transparent',
},
':focus::placeholder': {
color: '#7b808c',
},
':-webkit-autofill': {
webkitTextColor: '#333',
}
},
invalid: {
color: '#e41029',
':focus': {
color: '#e44d5f',
},
'::placeholder': {
color: '#FFCCA5',
},
}
},
fonts: [
"https://fonts.googleapis.com/css?family=Lato:400,700"
]
});
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
# tokenize() deprecated
Sends the card details to the payment gateway for tokenization. The payment gateway configured for the business entity (opens new window) specified during initialization is used for tokenization.
TIP
The generated temporary token expires after 30 minutes.
# Syntax
chargebee.tokenize(component, additionalData);
# Parameters
DETAILS
Card component object
# Return value
Returns a promise that resolves to a Chargebee nonce (temporary token) object.
# Example
// Create a card component.
const cardComponent = chargebee.createComponent('card');
cardComponent.mount('#card-component');
// Tokenize the card with additional customer data.
chargebee.tokenize(cardComponent, {
firstName: 'John',
lastName: 'Doe',
addressLine1: '1600 Amphitheatre Parkway',
addressLine2: 'Building 42',
city: 'Mountain View',
state: 'California',
stateCode: 'CA',
zip: '94039',
countryCode: 'US'
}).then((data) => {
console.log('Chargebee token:', data.token);
// Use the token to create a payment source or subscription.
}).catch((error) => {
console.error('Tokenization failed:', error);
// Handle tokenization error.
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# Response example
{
"token": "cb_XAKJhqUVXuhyiJRYgLQSakdkNQad"
}
2
3
# Card component object
The Card component object provides methods to manage the card component, including tokenization, 3DS authorization, event handling, and field management.
# tokenize()
Sends the card details to the payment gateway (opens new window) for tokenization. The payment gateway for processing the card details is selected based on smart routing (opens new window).
If multi business entity (opens new window) is configured, the payment gateway configured for the business entity specified during Chargebee.js initialization init() is selected here.
# Syntax
cardComponent.tokenize(additionalData)
# Parameters
DETAILS
# Return value
Returns a promise that resolves to a Chargebee token object with the following structure:
{
"token": "<chargebee-token>"
}
2
3
# Example
const cardComponent = chargebee.createComponent("card");
cardComponent.mount("#card-component");
cardComponent.tokenize({
firstName: "John",
lastName: "Doe",
addressLine1: "1600 Amphitheatre Parkway",
addressLine2: "Suite 100",
city: "Mountain View",
state: "California",
stateCode: "CA",
zip: "94039",
countryCode: "US",
}).then((data) => {
console.log('Chargebee token:', data.token);
}).catch((error) => {
console.error('Tokenization error:', error);
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# authorizeWith3ds()
Initiates 3D Secure (3DS) authorization for the card details entered in the card component fields. After successful payment authorization, the payment intent is returned with an authorized state. The paymentIntent ID can then be used to create a payment source (opens new window) or create a subscription (opens new window).
This method internally uses the 3DS Helper provided by Chargebee.
Using webhooks
Use webhooks (opens new window) for production use, instead of making the subscription creation request from the client-side, it's more secure and reliable to respond to webhooks from Chargebee on the server-side. Listen to the payment_intent_updated (opens new window) event via webhooks and create the subscription when the payment_intent.status (opens new window) is authorized.
# Syntax
cardComponent.authorizeWith3ds(paymentIntent, additionalData, callbacks)
# Parameters
DETAILS
# Return value
Returns a promise that resolves to an authorized payment intent object.
# Example
const cardComponent = chargebee.createComponent("card");
cardComponent.mount("#card-component");
function onSubmit() {
createPaymentIntent().then(paymentIntent => {
const additionalData = {
billingAddress: {
firstName: "John",
lastName: "Doe",
billingAddr1: "1600 Amphitheatre Parkway",
billingCity: "Mountain View",
billingState: "California",
billingStateCode: "CA",
billingZip: "94039",
billingCountry: "United States",
},
document: { //Required for EBANX gateway.
type: 'br_cpf',
number: '85351346893',
},
};
return cardComponent.authorizeWith3ds(paymentIntent, additionalData)
}).then((paymentIntent) => {
console.log('payment intent authorized', paymentIntent.id);
}).catch((error) => {
console.log('payment intent refused');
});
}
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
# EBANX document verification types
DETAILS
When using the EBANX gateway (opens new window), you must include the additionalData.document parameter for EBANX document verification (opens new window) when calling authorizeWith3ds(). The following table shows the required values for additionalData.document.type for different document types.
| Countries | Document | Parameter value additionalData.document.type |
|---|---|---|
| Argentina | CDI | cdi |
| Argentina | CUIL | cuil |
| Argentina | CUIT | cuit |
| Argentina | DNI | dni |
| Brazil | CPF | cpf |
| Brazil | CNPJ | cnpj |
| Chile | RUT | rut |
| Colombia | CC | cc |
| Colombia | CE | ce |
| Colombia | NIT | nit |
| Ecuador, Peru | DOC | doc |
| Uruguay | CI | ci |
# dLocal document verification types
DETAILS
When using the dLocal gateway (opens new window), you must include the additionalData.document parameter for dLocal document verification when calling authorizeWith3ds(). The following table shows the required values for additionalData.document.type for different document types.
| Countries | Document | Parameter value additionalData.document.type |
|---|---|---|
| Argentina | DNI | ar_dni |
| Argentina | CUIT | ar_cuit |
| Brazil | CPF | br_cpf |
| Brazil | CNPJ | br_cnpj |
| Chile | CI | cl_ci |
| Chile | RUT | cl_rut |
| Colombia | CC | co_cc |
| India | PAN | in_pan |
| Mexico | CURP | mx_curp |
| Peru | DNI | pe_dni |
# on()
Attaches event listeners to the card component. In Default mode, you can attach focus, blur, ready, and change events.
# Syntax
cardComponent.on(eventType, callbackFunction)
# Parameters
DETAILS
ready
focus
blur
change
Other than ready event, all callback functions will get the current state as argument, with the following properties,
- field String
Corresponding field type - type String
Event type for which the callback got triggered - complete Boolean
This will be true, if the fields are filled completely - error Object
If the component has any validation errors, the corresponding error message and error code are passed {name, message} - cardType String
Card number type
Example values are: mastercard, visa, amex, etc. - empty Boolean
If the component is empty
# Return value
Returns the card component object for method chaining.
# Example
cardComponent.on('ready', () => {
console.log("field is ready to collect data");
})
cardComponent.on('focus', () => {
// Triggered when field is focused
})
cardComponent.on('blur', () => {
// Triggered when field is blurred
})
cardComponent.on('change', (currentState) => {
// This event will be triggered whenever the state changes from "empty" -> "complete" -> "valid" / "invalid"
// The validation errors for this field can be checked here
console.log(currentState.error);
})
2
3
4
5
6
7
8
9
10
11
12
13
14
# at() deprecated
Specifies the container element where the card component will be mounted. This method is only needed when using the card component in Default mode. Accepts either a CSS selector or a DOM Element.
# Syntax
cardComponent.at(domElement);
# Return value
Returns the card component object for method chaining.
# Example
cardComponent.at("#card-component");
# mount()
Inserts the card component into the DOM. The component becomes ready for collecting card details only after this method is called. The container element for mounting must be specified here. This method accepts either a DOM Element or a CSS Selector.
# Syntax
cardComponent.mount('#card-component');
# Parameters
# Return value
Returns a promise that resolves after successfully mounting the card component.
# focus()
Sets keyboard focus (opens new window) on the card component. This method is useful when you want to programmatically focus on the card component.
# Syntax
cardComponent.focus()
# Example
const cardComponent = chargebee.createComponent("card");
cardComponent.mount("#card-component");
function onPageLoad() {
cardComponent.focus();
}
2
3
4
5
6
# blur()
Removes keyboard focus (opens new window) from the card component. This method is useful when you want to programmatically blur the card component.
# Syntax
cardComponent.blur();
# clear()
Clears the contents of card fields.
# Syntax
cardComponent.clear();
# update()
Updates the configuration for card fields.
# Syntax
cardComponent.update(options)
# Parameters
DETAILS
# Example
cardComponent.update({
placeholder: '4111 1111 1111 1111'
})
2
3
# validateCardDetails()
Use this method to validate the entered card details.
# Syntax
cardComponent.validateCardDetails()
# Return value
Returns a promise that resolves to true if card details are valid, and false if invalid.
# Example
cardComponent.validateCardDetails().then(isValid => {
if(isValid) {
console.log('Card details are valid')
} else {
console.log('Card details are invalid')
}
})
2
3
4
5
6
7
# getBinData()
Retrieves the Bank Identification Number (BIN) information of a card number entered in the card fields. BIN data is returned only if the entered card number is valid. To access BIN data, add your domain, where Chargebee.js is integrated, to the domain allowlist (opens new window) in Chargebee Billing.
# Syntax
cardComponent.getBinData()
# Return value
Returns BIN data object if the card number is valid, or undefined if invalid.
{
"bin": "411111",
"last4": "1111"
}
2
3
4
# Example
const cardComponent = chargebee.createComponent("card");
cardComponent.mount("#card-component");
const binData = cardComponent.getBinData();
if (binData) {
console.log('BIN:', binData.bin);
console.log('Last 4 digits:', binData.last4);
}
2
3
4
5
6
7
8
# get3DSHandler()
Retrieves the Chargebee.js 3DS payment handler instance. This method can be accessed only after the 3DS payment transaction has been initiated with authorizeWith3ds().
# Syntax
cardComponent.get3DSHandler()
# Return value
Returns a 3DS handler instance.
# Example
const cardComponent = chargebee.createComponent("card");
cardComponent.mount("#card-component");
cardComponent.authorizeWith3ds(paymentIntent, {
callbacks: {
challenge: (redirect_url) => {
// Present challenge URL to user in an iframe or popup window
window.open(redirect_url, "_blank");
},
},
}).then((intent) => {
console.log('Authorization successful');
}).catch((error) => {
console.error('Authorization failed:', error);
});
function onWindowClose() {
// Call this method when user closes the popup window or iframe
const threeDSHandler = cardComponent.get3DSHandler();
threeDSHandler.cancel();
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# createField()
Creates individual card fields (number, cvv, and expiry) for use in Fields mode. This method allows you to display card fields separately instead of as a single component. You can pass options to override options passed at the component level.
# Syntax
cardComponent.createField(fieldType, options)
# Parameters
DETAILS
number
cvv
expiry
# Return value
Returns a Card Field object that provides methods to manage the individual field.
# Example
cardComponent.createField("number", {
placeholder: "4111 1111 1111 1111",
style: {
// override styles for default state
base: {
color: '#333',
fontWeight: '500',
fontFamily: 'Poppins,-apple-system, BlinkMacSystemFont, Segoe UI, Helvetica Neue, sans-serif',
fontSize: '16px',
fontSmoothing: 'antialiased',
':focus': {
color: '#424770',
},
'::placeholder': {
color: 'transparent',
},
':focus::placeholder': {
color: '#7b808c',
},
},
invalid: {
color: '#e41029',
':focus': {
color: '#e44d5f',
},
'::placeholder': {
color: '#FFCCA5',
},
}
},
});
cardComponent.createField("cvv")
cardComponent.createField("expiry")
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
# Card field object
The Card field object allows you to specify where individual fields should be mounted and add event listeners at the field level. Use the createField() method to create card field objects.
const numberField = cardComponent.createField("number");
const expiryField = cardComponent.createField("expiry");
const cvvField = cardComponent.createField("cvv");
2
3
# at()
Specifies the container element where the card field will be mounted. This method is only needed when using the card component in Fields mode. Accepts either a CSS selector or a DOM Element.
# Syntax
cardField.at(domElement)
# Parameters
# Return value
Returns the card field object for method chaining.
# Example
cardField.at("#card-field");
# on()
Attaches event listeners to the card field. In Fields mode, only ready and change events can be attached.
# Syntax
cardField.on(eventType, callbackFunction)
# Parameters
DETAILS
ready
focus
blur
change
Other than ready event, all callback functions will get the current state as argument, with the following properties,
- field String
Corresponding field type - type String
Event type for which the callback got triggered - complete Boolean
This will be true, if the fields are filled completely - error Object
If the component has any validation errors, the corresponding error message and error code are passed {name, message} - cardType String
Card number type
Example values are: mastercard, visa, amex, etc. - empty Boolean
If the component is empty
# Return value
Returns the card field object for method chaining.
# Example
const numberField = cardComponent.createField("number");
numberField.on('ready', () => {
console.log("Field is ready to collect data.");
});
numberField.on('change', (currentState) => {
// This event will be triggered whenever the state changes
// Sample status object for change event on number field with error:
// {
// type: "change", // event type
// field: "number", // field type
// cardType: "visa",
// complete: false,
// empty: false,
// error: { // Validation error object
// name: "CARD_NUMBER_INCOMPLETE",
// message: "Invalid card"
// }
// }
console.log(currentState.error);
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# update()
Updates the styling of the field.
# Syntax
cardField.update(options)
# Parameters
DETAILS
# Return value
Returns the card field object for method chaining.
# Example
cardField.update({
style: {
base: {
color: '#fff',
fontSize: `18px`
}
}
});
2
3
4
5
6
7
8
# focus()
Sets keyboard focus (opens new window) on the field.
# Syntax
cardField.focus();
# blur()
Removes keyboard focus (opens new window) from the field.
# Syntax
cardField.blur();
# clear()
Clears the contents of the field.
# Syntax
cardField.clear();
# mount()
Mounts the field to the specified DOM element. This method accepts a query selector for the HTML element, or the HTML element itself where the field should be mounted.
# Syntax
cardField.mount(domElement);
# Parameters
# Return value
Returns a promise that resolves once the field is successfully mounted.
# Example
// Usage 1
cardField.mount("#number-field");
// Usage 2
cardField.at("#number-field").mount();
2
3
4
5
# Validation error object
Whenever a validation error occurs, the error object is passed to the callback function attached to the change event. This applies to both card component and card field objects.
card_number_invalid
card_number_incomplete
invalid_card
card_expiry_past
card_expiry_invalid
card_expiry_incomplete
card_cvv_incomplete
card_cvv_invalid
# Chargebee JS wrappers
Chargebee provides framework-specific wrappers for Angular, React, and Vue that simplify the integration of card components and fields. These wrappers offer native directives and components that you can use directly in your applications.
# Angular
The card component and its fields are available as directives (cbCardField, cbNumberField, cbExpiryField, cbCvvField) in the Angular wrapper (opens new window).
# Card component directive
The following attributes can be set on the cbCardField directive:
DETAILS
# Example
...
<div
cbCardField
id="card-field"
[fonts]="fonts"
[styles]="styles"
[locale]="locale"
[classes]="classes"
[placeholder]="placeholder"
></div>
...
2
3
4
5
6
7
8
9
10
11
export class AppComponent {
...
styles = {
// Styles for default field state
base: {
color: '#333',
fontWeight: '500',
fontFamily: 'Lato, Segoe UI, Helvetica Neue, sans-serif',
fontSize: '16px',
fontSmoothing: 'antialiased',
':focus': {
color: '#424770',
},
'::placeholder': {
color: 'transparent',
},
':focus::placeholder': {
color: '#7b808c',
},
},
// Styles for invalid field state
invalid: {
color: '#e41029',
':focus': {
color: '#e44d5f',
},
'::placeholder': {
color: '#FFCCA5',
},
}
};
// Custom fonts
fonts = [
'https://fonts.googleapis.com/css?family=Lato:400,700'
];
// Custom placeholder
placeholder = {
number: '4111 1111 1111 1111',
expiry: 'MM / YY',
cvv: 'CVV'
};
// Custom classes
classes = {
focus: 'focus',
invalid: 'invalid',
empty: 'empty',
complete: 'complete',
};
// Locale
locale = 'en';
...
}
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
# Attach event listeners
You can attach the following event listeners to the cbCardField directive:
readyfocusblurchange
# Example
<div
id="card-field"
cbCardField
class="fieldset field"
(ready)="onReady($event)"
(focus)="onFocus($event)"
(blur)="onBlur($event)"
(change)="onChange($event)"
></div>
2
3
4
5
6
7
8
9
# Field directives
The following attributes can be set on the field directives (cbNumberField, cbExpiryField, cbCvvField):
DETAILS
# Attach event listeners
You can attach the following event listeners to the field directives:
readyfocusblurchange
# Example
<div
id="card-number"
cbNumberField
class="fieldset field"
(ready)="onReady($event)"
(focus)="onFocus($event)"
(blur)="onBlur($event)"
(change)="onChange($event)"
></div>
2
3
4
5
6
7
8
9
# React
The following components are available in the React wrapper (opens new window): CardComponent, CardNumber, CardExpiry, and CardCVV.
# Card component
The following props can be passed to the CardComponent:
DETAILS
# Example
<CardComponent
className="field"
ref={this.CardRef}
icon={false}
fonts={fonts}
classes={classes}
locale={locale}
styles={styles}
placeholder={placeholder}
/>
2
3
4
5
6
7
8
9
10
# Attach event listeners
You can attach the following event listeners to the CardComponent:
readyfocusblurchange
# Example
<CardComponent
className="field"
ref={this.CardRef}
onReady={this.onReady}
onFocus={this.onFocus}
onBlur={this.onBlur}
onChange={this.onChange}
/>
2
3
4
5
6
7
8
# Card field components
The following props can be passed to the field components (CardNumber, CardExpiry, CardCVV):
DETAILS
# Example
<CardNumber
className="field"
icon={false}
styles={styles}
placeholder={"4242 4242 4242 4242"}
/>
2
3
4
5
6
# Attach event listeners
You can attach the following event listeners to the card field components:
readyfocusblurchange
# Example
<CardNumber
className="field"
onReady={this.onReady}
onFocus={this.onFocus}
onBlur={this.onBlur}
onChange={this.onChange}
/>
2
3
4
5
6
7
# Vue
The following components are available in the Vue wrapper (opens new window): CardComponent, CardNumber, CardExpiry, and CardCVV.
# Card component
The following props can be passed to the CardComponent:
DETAILS
# Example
<card-component
class="fieldset"
ref="cardComponent"
:fonts="fonts"
:styles="styles"
:locale="locale"
:classes="classes"
:icon="icon"
:placeholder="placeholder"
></card-component>
2
3
4
5
6
7
8
9
10
# Attach event listeners
You can attach the following event listeners to the CardComponent:
readyfocusblurchange
# Example
<card-component
class="fieldset"
ref="cardComponent"
@ready="onReady"
@change="onChange"
@focus="onFocus"
@blur="onBlur"
></card-component>
2
3
4
5
6
7
8
# Card field components
The following props can be passed to the field components (CardNumber, CardExpiry, CardCVV):
DETAILS
# Example
<card-number
class="fieldset"
:styles="styles"
:classes="classes"
:placeholder="placeholder"
></card-number>
2
3
4
5
6
# Attach event listeners
You can attach the following event listeners to the card field components:
readyfocusblurchange
# Example
<card-number
class="fieldset"
@ready="onReady"
@change="onChange"
@focus="onFocus"
@blur="onBlur"
></card-number>
2
3
4
5
6
7
