# Card Components
The cards and components can be integrated with Chargebee by using 3D Secure, also referred to as 3DS popularly. The integration can be done without 3DS as well. Learn more.
# createComponent
This function is used to create a component based on the componentType and the options passed. Currently we support only the creation of card components, we will start supporting other component types soon.
Chargebee Instance object can be used to create components.
# Syntax
cbInstance.createComponent(componentType, options)
# Parameters
card
# Return value
# Example
cbInstance.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
# Card component object
# tokenize
Send the card details to the payment gateway 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, then the payment gateway configured for the business entity specified during Chargebee.js initialization init is selected here.
# Syntax
cardComponent.tokenize(additionalData)
# Parameters
# Return value
Promise that resolves Chargebee token object.
{
// Temp token from chargebee
"token": "cb_tok_169lsYTCUvZ0l4oKl",
}
2
3
4
# Example
let cardComponent = cbInstance.createComponent("card");
cbInstance.tokenize(cardComponent, {
firstName: "John",
lastName: "Doe",
addressLine1: "1600 Amphitheatre Parkway",
addressLine2: "<replace with sample>",
city: "Mountain View",
state: "California",
stateCode: "CA",
zip: "94039",
countryCode: "US",
}).then((data) => {
console.log('chargebee token', data.token);
}).catch((error) => {
console.log(error);
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# authorizeWith3ds
This function is used to initiate 3DS authorization against the card details entered in the card component fields. After successful payment authorization, the payment intent is returned with 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
# Return value
Promise that resolves to authorized payment intent object.
# Example
const cardComponent = cbInstance.createComponent("card");
cardComponent.mount("#card-field");
function onSubmit() {
createPaymentIntent().then(paymentIntent => {
const additionalData = {
firstName: "John",
lastName: "Doe",
billingAddr1: "1600 Amphitheatre Parkway",
billingCity: "Mountain View",
billingState: "California",
billingStateCode: "CA",
billingZip: "94039",
billingCountry: "United States",
};
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
# on
This function is used to attach listeners to the card component. In Default mode, focus, blur, ready, and change events can be attached.
# Syntax
cardComponent.on(eventType, callbackFunction)
# Parameters
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 card component object
# 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 whenver 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
# createField
If you want to display the card component in Fields mode, you need to use this method to create number, cvv and expiry fields. You can pass options to override options passed at the component level.
# Syntax
cardComponent.createField(fieldType, options)
# Parameters
number
cvv
expiry
# Return value
# Example
cardComponent.createField("number", {
placeholder: "4111 1111 1111 1111",
styles: {
// 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
# mount
The components will be inserted into the DOM and will be ready for collecting card details only after this method gets called. The container element for mounting can also be specified here. 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 component.
# focus
Use this method to programatically focus on the card field.
# Syntax
cardComponent.focus()
# Example
var cardComponent;
function onPageLoad() {
cardComponent.focus();
}
2
3
4
# blur
Use this method to programatically trigger blur event on card fields.
# Syntax
cardComponent.blur();
# clear
Use this method to clear contents of card fields.
# Syntax
cardComponent.clear();
# update
Use this method to update the configuration for card fields.
# Syntax
cardComponent.update(options)
# Parameters
# 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 a boolean value 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
# Card field object
Card field object is used to specify where the fields should be mounted and add event listeners at the individual field level.
let numberField = cardComponent.createField("number")
let expiryField = cardComponent.createField("expiry")
let cvvField = cardComponent.createField("cvv")
2
3
Use createField method to create a card field object.
# at
This is needed only if you are using the card component in the field mode. This function is used to specifiy container element where the component will be mounted. Accepts either the CSS selector or a DOM Element.
# Syntax
cardField.at(domElement)
# Parameters
# Return value
Returns the card field
# Example
cardField.at("#card-field");
# on
This function is used to attach listeners to the card component. In Fields mode only ready and change events can be attached.
# Syntax
cardField.on(eventType, callbackFunction)
# Parameters
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 card field object
# Example
// 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"
}
}
2
3
4
5
6
7
8
9
10
11
12
# update
This function is used to programatically update the styling of field.
# Syntax
cardField.update(options)
# Parameters
# Return value
Returns the card field object.
# Example
cardField.update({
style: {
base: {
color: '#fff',
fontSize: `18px`
}
}
});
2
3
4
5
6
7
8
# focus
This function is used to programatically focus on the field.
# Syntax
cardField.focus();
# blur
This function is used to programatically blur the field.
# Syntax
cardField.blur();
# clear
This function is used to clear the contents of the field.
# Syntax
cardField.clear();
# mount
This function optionally accepts a query selector for the HTML element, or the HTML element itself where the field has to be mounted.
# Syntax
cardField.mount(domElement);
# Parameters
# Return value
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
