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.
Supported Gateways
See the list of gateways supported by Hosted Components & Fields and ensure that yours is supported.
This function is used to initialize Chargebee with your site, domain name and publishable key(opens new window). The 'chargebee instance' object returned as result of initialization can be used to create the components.
Your custom domain. Eg: https://billing.yourdomain.com
publishableKey
String Required
Your publishable API key.
businessEntityId
String
The unique ID of the business entity under whose context the cart object or the drop-in script should work. If not provided, the default business entity defined for the site is considered. Note:This parameter is applicable only when multiple business entities have been created for the site.
var cbInstance = Chargebee.init({site:"site-name",// your test sitedomain:"https://mybilling.acme.com"// this is an optional parameter.publishableKey:"test__"})
This function is used to load the given module. Currently there is only one module, we will be adding more modules to support different functionality soon.
All components/fields functionality can be used only when module "components" is loaded. If you are using our wrappers, we will take care of loading the module, otherwise register the components after the promise is resolved
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.
Pass card component object or component type for which you want to get Chargebee token
object
Allowed Values:
Card component object
additionalData
Data that is collected at your end.
object
For card component, you can pass additional information like firstName, lastName. Chargebee will generate temporary token for all these details along with the card information collected via our components.
This is needed only if you are using the card component in the Default mode. This function is used to specifiy container element where the component will be mounted. Accepts either the CSS selector or a DOM Element.
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.
Our 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
This function is used to attach listeners to the card component. In Default mode, focus, blur, ready, and change events can be attached. In Fields mode only ready and change events can be attached.
Function that will be called when the corresponding event fires. Other than ready event, all callback functions will get the current state as argument, with the following properties,
fieldString Corresponding field type
typeString Event type for which the callback got triggered
completeBoolean This will be true, if the fields are filled completely
errorObject If the component has any validation errors, the corresponding error message and error code are passed {name, message}
cardTypeString Card number type Example values are: mastercard, visa, amex, etc.
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);});
Additional information that you collect as part of card details can be passed. These information will be used while creating a payment source for the customer.
A paymentIntent needs to be created before using this method. Click here to know more
This function is used to initiate 3DS Authorization against the card details entered in the card component fields. After a successful 3DS flow, the payment intent passed will change to 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.
Additional information that needs to be passed for improving the chances of frictionless checkout flow.
plan
String
Plan name
billingAddress
Object Hide properties
Card Billing Address
firstName
String Required if Worldpay gateway is used
First name associated with billing address
lastName
String
Last name associated with billing address
phone
String
Phone number associated with the billing address
addressLine1
String
Billing address line 1 (eg. number, street, etc).
addressLine2
String
Billing address line 2 (eg. suite, apt #, etc.).
addressLine3
String
Billing address line 3 (eg. suite, apt #, etc).
city
String
City or locality name
state
String
State
stateCode
String
2 letter code for US states or equivalent
countryCode
String
2 letter country code
zip
String
Zip code or postal code
customerBillingAddress
Object Hide properties
Customer's Billing Address
firstName
String Required if Worldpay gateway is used
First name associated with billing address
lastName
String
Last name associated with billing address
phone
String
Phone number associated with the billing address
addressLine1
String
Billing address line 1 (eg. number, street, etc).
addressLine2
String
Billing address line 2 (eg. suite, apt #, etc.).
addressLine3
String
Billing address line 3 (eg. suite, apt #, etc).
city
String
City or locality name
state
String
State
stateCode
String
2 letter code for US states or equivalent
countryCode
String
2 letter country code
zip
String
Zip code or postal code
shippingAddress
Object Hide properties
Shipping Address
firstName
String Required if Worldpay gateway is used
First name associated with shipping address
lastName
String
Last name associated with shipping address
phone
String
Phone number associated with the shipping address
addressLine1
String
Shipping address line 1 (eg. number, street, etc).
addressLine2
String
Shipping address line 2 (eg. suite, apt #, etc.).
addressLine3
String
Shipping address line 3 (eg. suite, apt #, etc).
city
String
City or locality name
state
String
State
stateCode
String
2 letter code for US states or equivalent
countryCode
String
2 letter country code
zip
String
Zip code or postal code
email
String Required if Worldpay gateway is used
Mail ID of the customer.
phone
String
Phone number
mandate
Object Hide properties
Enabling this parameter will request Additional Factor Authentication (AFA) and mandate setup to the gateway. Applicable only for cards issued in India.
requireMandate
Boolean
Set the value as `true` to create a mandate. The default value is `false`.
description
String
Send the plan name in this description. This plan name will appear on the AFA page.
callbacks
Object Hide properties
Callbacks to be used for this operation.
change
Function
This function will be called during each step of 3DS flow
success
Function
This function will be called if 3DS Authorization is successful
error
Function
This function will be called if 3DS Authorization has failed
challenge
Function
When this callback is implemented, the transaction will proceed in a redirect workflow if supported by the gateway. This callback function will be called with a redirect URL when the 3DS transaction requires a challenge. This workflow is currently supported by Adyen, Braintree and Stripe payment gateways.
Use this method to access 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.
This method is used to retrieve Chargebee.js 3DS payment handler instance. This method can be accessed only after the 3DS payment transaction has been initiated with authoriseWith3ds method.
cardComponent
.authorizeWith3ds({callbacks:{challenge:(redirect_url)=>{// Present challenge URL to user in an iframe or popup window
window.open(redirect_url,"_blank");},},}).then((intent)=>{
console.log("success");}).catch((error)=>{
console.error(error);});functiononWindowClose(){// Call this method when user closes the popup window / iframeconst threeDSHandler = cardComponent.get3DSHandler();
threeDSHandler.cancel();}
Function that will be called when the corresponding event fires. Other than ready event, all callback functions will get the current state as argument, with the following properties,
fieldString Corresponding field type
typeString Event type for which the callback got triggered
completeBoolean This will be true, if the fields are filled completely
errorObject If the component has any validation errors, the corresponding error message and error code are passed {name, message}
cardTypeString Card number type Example values are: mastercard, visa, amex, etc.
emptyBoolean If the component is empty
// sample status object for change event on number field with error{type:"change"// event typefield:"number"// field typecardType:"visa"complete:falseempty:falseerror:{// Validation error objectname:"CARD_NUMBER_INCOMPLETE",message:"Invalid card"}}
numberField.on("ready",()=>{
console.log("field is ready to collect data");});
numberField.on("focus",()=>{// Triggered when field is focused});
numberField.on("blur",()=>{// Triggered when field is blurred});
numberField.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);});
The card component and its fields are available as directives(cbCardField, cbNumberField, cbExpiryField, cbCvvField) in Angular wrapper(opens new window).
