API Reference

This reference is for integrating "components and fields" into your application.

Chargebee object

init

This function is used to initialize Chargebee with your site, domain name and publishable key. The 'chargebee instance' object returned as result of initialization can be used to create the components.

Syntax

Chargebee.init(options)

Parameters

options
Object Required Hide properties
site
String Required
Your site name
domain
String Required if custom domain is enabled
Your custom domain
Eg: https://billing.yourdomain.com
publishableKey
String Required
Your publishable API key

Return value

Chargebee instance object

Example

var chargebeeInstance = Chargebee.init({
  site: "site-name", // your test site
  domain: "https://mybilling.acme.com" // this is an optional parameter.
  publishableKey: "test__"
})


getInstance

This function will return 'chargebee instance' object.

Syntax

Chargebee.getInstance();

Return value

Chargebee instance object

Error will be thrown if instance is not created.

Chargebee instance object

Chargebee instance object is used to create components and tokenize card information.

load

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

Syntax

chargebeeInstance.load(moduleName)

Parameters

moduleName
String Required
Name of the module to load
Allowed Values: components

Return value

Promise that resolves after that corresponding module has been loaded

Example

chargebeeInstance.load('components').then(() => {
  // components can be mounted
});


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.

Syntax

chargebeeInstance.createComponent(componentType, options)

Parameters

componentType
String Required
Allowed Values: card
options
Object Hide properties
currency
String
Currency code in ISO 4217 format (USD, EUR). By default, base currency code will be used
icon
Boolean
Card type icon
locale
String
Locale code in ISO 639-1 format (en, fr). By default, `en` will be used
placeholder
Object View properties
Placeholder texts for number, cvv & expiry fields
classes
Object View properties
Class names that will be added to all container div elements for different states. Using this you can customize our components for different states.
fonts
Array<Object | String>
Define the list of font definitions or font URLs
Object Hide properties
Font definition that will be used in our components
fontFamily
cssProperty Required
Font name
src
cssProperty Required
Source URL. Google Web Font or Typekit Web Font URL
fontStyle
cssProperty
fontWeight
cssProperty
String
Web font URL (Either Google Web Font or Typekit Web Font)
style
Object View properties
Inline styles that needs to be applied to all input fields.

Return value

Card component object

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',
      },
    },

    invalid: {
      color: '#e41029',

      ':focus': {
        color: '#e44d5f',
      },
      '::placeholder': {
        color: '#FFCCA5',
      },
    }
  },
  
  fonts: [
    "https://fonts.googleapis.com/css?family=Lato:400,700"
  ]
});


tokenize

This function is used to get the Chargebee token for the card details.

Syntax

cbInstance.tokenize(component, additionalData)

Parameters

component
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, email, address. Chargebee will generate temporary token for all these details along with the card information collected via our components.
firstName
string
First Name
lastName
string
Last Name
billingAddr1
string
Billing Address line 1
billingAddr2
string
Billing Address line 2
billingCity
string
City
billingState
string
State
billingStateCode
string
State Code
billingZip
string
Zip
billingCountry
string
Country

Return value

Promise that resolves to a Chargebee nonce (temp token) object.

Example

let cardComponent = cbInstance.createComponent("card");
cbInstance.tokenize(cardComponent, {
  firstName: "John",
  lastName: "Doe",
  billingAddr1: "1600 Amphitheatre Parkway",
  billingCity: "Mountain View",
  billingState: "California",
  billingStateCode: "CA",
  billingZip: "94039",
  billingCountry: "United States",
}).then((data) => {
  console.log('chargebee token', data.token);
}).catch((error) => {
  console.log(error);
});

Sample Response

{
  "token": "cb_XAKJhqUVXuhyiJRYgLQSakdkNQad"
}

Card component object

Card component object is used to specify where the components should be mounted and add listeners for various events.

at

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.

Syntax

cardComponent.at(domElement)

Return value

Returns the object itself.

Example

cardComponent.at("#card-field");


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

fieldType
String Required
Allowed Values: number
cvv
expiry
options
Object Hide properties
placeholder
String
Placeholder text for corresponding input field
icon
Boolean
Card type icon
style
Object View properties
Inline styles that needs to be applied to all input fields.

Return value

Field object.

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


mount

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

Syntax

cardComponent.mount('#card-component');

Return value

Returns a promise that resolves after successfully mounting the component.



on

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.

Syntax

cardComponent.on(eventType, callbackFunction)

Parameters

eventType
String Required
Allowed Values: ready
focus
blur
change
callbackFunction
Function Required
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,
  • 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 object itself.

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


tokenize

This function is used to get Chargebee token for the data entered in our component.

Syntax

cbComponent.tokenize(additionalData)

Parameters

additionalData
Object Hide properties
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.
firstName
String
lastName
String
email
String
addressLine1
String
addressLine2
String
addressLine3
String

Return value

Promise that resolves to a Chargebee nonce (temp token) object.

Example

let cardComponent = cbInstance.createComponent("card");
cardComponent.tokenize({
  firstName: "John",
  lastName: "Doe",
  billingAddr1: "1600 Amphitheatre Parkway",
  billingCity: "Mountain View",
  billingState: "California",
  billingStateCode: "CA",
  billingZip: "94039",
  billingCountry: "United States",
}).then((data) {
  console.log('Chargebee token', data.token);
}).catch(error) {
  console.log(error);
};

authorizeWith3ds

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. After a successful 3DS flow, the payment intent passed will move to authorized state. Now, this paymentIntent ID can be used to create a payment source / create a subscription.

This method internally uses the 3DS Helper Module provided by Chargebee

Syntax

cbComponent.authorizeWith3ds(paymentIntent, additionalData, callbacks)

Parameters

paymentIntent
Payment Intent Required
additionalData
Object Hide properties
Additional information that needs to be passed for improving the chances of frictionless checkout
billingAddress
Object View properties
Billing Address
email
String
E-mail Address
phone
String
Phone number
callbacks
Object Hide properties
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

Return value

Promise that resolves to authorized payment intent object.

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

at

This function is used to specifiy container element where the field will be mounted. Accepts either the DOM element or the CSS Selector

Syntax

numberField.at(domElement)

Return value

Returns the object itself.

Example

cvvField.at("#cvv-field");


on

This function is used to attach event listener for focus, blur, change and ready events.

Syntax

numberField.on('change', callbackFunction)

Parameters

eventType
String Required
Allowed Values: ready
focus
blur
change
callbackFunction
Function Required
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,
  • 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
// 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"
  }
}

Return value

Returns the object itself.

Example

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

Validation error object

Whenever validation error happens, we pass the below error object to the callback function attached to change event.

errorCode
String
Allowed Values: card_number_invalid
card_number_incomplete
invalid_card
card_expiry_past
card_expiry_invalid
card_expiry_incomplete
card_cvv_incomplete
card_cvv_invalid
message
String
Corresponding error message based on the locale set. If you want to display error message, you can customize based on error codes.

Chargebee JS wrappers

Angular

The card component and its fields are available as directives(cbCardField, cbNumberField, cbExpiryField, cbCvvField) in Angular wrapper.

Card Component directive

The following attributes can be set to the card component directive cbCardField

fonts
Array<Object | String>
Define the list of font definitions or font URLs
Object Hide properties
Font definition that will be used in our components
fontFamily
cssProperty Required
Font name
src
cssProperty Required
Source URL. Google Web Font or Typekit Web Font URL
fontStyle
cssProperty
fontWeight
cssProperty
String
Web font URL (Either Google Web Font or Typekit Web Font)
classes
Object Hide properties
Class names that will be added to all container div elements for different states. Using this you can customize our components for different states.
focus
String
Pass the class name that will be applied during field focus.
empty
String
Pass the class name that will be applied when the field is empty. This will be applied only after blur event is fired on the field.
invalid
String
Pass the class name that will be applied when the field is invalid. This will be applied only after blur event is fired on the field.
complete
String
Pass the class name that will be applied when the field is complete. This will be applied only after blur event is fired on the field.
locale
String
Locale code in ISO 639-1 format (en, fr). By default, `en` will be used
style
Object Hide properties
Inline styles that needs to be applied to all input fields.
base
Object View properties
Pass the set of css properties that needs to be applied on default state.
empty
Object View properties
Pass the set of css properties that needs to be applied on empty state
invalid
Object View properties
Pass the set of css properties that needs to be applied on invalid state
placeholder
Object Hide properties
Placeholder texts for number, cvv & expiry fields
number
string
Given text will be applied as a placeholder for number field
expiry
string
Given text will be applied as a placeholder for expiry field
cvv
string
Given text will be applied as a placeholder for cvv field

Example:

...
<div cbCardField id='card-field' 
  [fonts]="fonts"
  [styles]="styles"
  [locale]="locale"
  [classes]="classes"
  [placeholder]="placeholder"
></div>
...
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';
...
}

Attaching event listeners

The following events can be attached to the card component directive cbCardField

  • ready
  • focus
  • blur
  • change

Example

 <div id="card-field" cbCardField class="fieldset field" 
    (ready)="onReady($event)"
    (focus)="onFocus($event)"
    (blur)="onBlur($event)"
    (change)="onChange($event)"
  ></div>

Field directives

The following attributes can be set to the field directives cbNumberField, cbExpiryField, cbCvvField

placeholder
String
Placeholder text for corresponding input field
style
Object Hide properties
Inline styles that needs to be applied to all input fields.
base
Object View properties
Pass the set of css properties that needs to be applied on default state.
empty
Object View properties
Pass the set of css properties that needs to be applied on empty state
invalid
Object View properties
Pass the set of css properties that needs to be applied on invalid state

Attaching event listeners

The following events listeners can be attached to the card component directive cbCardField

  • ready
  • focus
  • blur
  • change

Example

 <div id="card-number" cbNumberField class="fieldset field" 
    (ready)="onReady($event)"
    (focus)="onFocus($event)"
    (blur)="onBlur($event)"
    (change)="onChange($event)"
  ></div>

React

The following components are available in React wrapper: CardComponent, CardNumber, CardExpiry, CardCVV.

Card Component

The following props can be passed to the card Component CardComponent

fonts
Array<Object | String>
Define the list of font definitions or font URLs
Object Hide properties
Font definition that will be used in our components
fontFamily
cssProperty Required
Font name
src
cssProperty Required
Source URL. Google Web Font or Typekit Web Font URL
fontStyle
cssProperty
fontWeight
cssProperty
String
Web font URL (Either Google Web Font or Typekit Web Font)
classes
Object Hide properties
Class names that will be added to all container div elements for different states. Using this you can customize our components for different states.
focus
String
Pass the class name that will be applied during field focus.
empty
String
Pass the class name that will be applied when the field is empty. This will be applied only after blur event is fired on the field.
invalid
String
Pass the class name that will be applied when the field is invalid. This will be applied only after blur event is fired on the field.
complete
String
Pass the class name that will be applied when the field is complete. This will be applied only after blur event is fired on the field.
locale
String
Locale code in ISO 639-1 format (en, fr). By default, `en` will be used
style
Object Hide properties
Inline styles that needs to be applied to all input fields.
base
Object View properties
Pass the set of css properties that needs to be applied on default state.
empty
Object View properties
Pass the set of css properties that needs to be applied on empty state
invalid
Object View properties
Pass the set of css properties that needs to be applied on invalid state
placeholder
Object Hide properties
Placeholder texts for number, cvv & expiry fields
number
string
Given text will be applied as a placeholder for number field
expiry
string
Given text will be applied as a placeholder for expiry field
cvv
string
Given text will be applied as a placeholder for cvv field

Example

 <CardComponent className="field"
    ref={this.CardRef}
    icon={false}
    fonts={fonts}
    classes={classes}
    locale={locale}
    styles={styles}
    placeholder={placeholder}
/>

Attaching event listeners

The following events listeners can be attached to card component CardComponent

  • ready
  • focus
  • blur
  • change

Example

<CardComponent className="field"
    ref={this.CardRef}
    onReady={this.onReady}
    onFocus={this.onFocus}
    onBlur={this.onBlur}
    onChange={this.onChange}
/>

Card Field Components

The following props can be passed to the field Components CardNumber, CardExpiry, CardCVV

placeholder
String
Placeholder text for corresponding input field
style
Object Hide properties
Inline styles that needs to be applied to all input fields.
base
Object View properties
Pass the set of css properties that needs to be applied on default state.
empty
Object View properties
Pass the set of css properties that needs to be applied on empty state
invalid
Object View properties
Pass the set of css properties that needs to be applied on invalid state

Example

<CardNumber className="field"
  icon={false}
  styles={styles}
  placeholder={"4242 4242 4242 4242"}
/>

Attaching event listeners

The following events listeners can be attached to card fields

  • ready
  • focus
  • blur
  • change

Example

<CardNumber className="field"
    onReady={this.onReady}
    onFocus={this.onFocus}
    onBlur={this.onBlur}
    onChange={this.onChange}
/>

Vue

The following components are available in Vue wrapper: CardComponent, CardNumber, CardExpiry, CardCVV

Card Component

The following props can be passed to the card Component CardComponent

fonts
Array<Object | String>
Define the list of font definitions or font URLs
Object Hide properties
Font definition that will be used in our components
fontFamily
cssProperty Required
Font name
src
cssProperty Required
Source URL. Google Web Font or Typekit Web Font URL
fontStyle
cssProperty
fontWeight
cssProperty
String
Web font URL (Either Google Web Font or Typekit Web Font)
classes
Object Hide properties
Class names that will be added to all container div elements for different states. Using this you can customize our components for different states.
focus
String
Pass the class name that will be applied during field focus.
empty
String
Pass the class name that will be applied when the field is empty. This will be applied only after blur event is fired on the field.
invalid
String
Pass the class name that will be applied when the field is invalid. This will be applied only after blur event is fired on the field.
complete
String
Pass the class name that will be applied when the field is complete. This will be applied only after blur event is fired on the field.
locale
String
Locale code in ISO 639-1 format (en, fr). By default, `en` will be used
style
Object Hide properties
Inline styles that needs to be applied to all input fields.
base
Object View properties
Pass the set of css properties that needs to be applied on default state.
empty
Object View properties
Pass the set of css properties that needs to be applied on empty state
invalid
Object View properties
Pass the set of css properties that needs to be applied on invalid state
placeholder
Object Hide properties
Placeholder texts for number, cvv & expiry fields
number
string
Given text will be applied as a placeholder for number field
expiry
string
Given text will be applied as a placeholder for expiry field
cvv
string
Given text will be applied as a placeholder for cvv field

Example

<card-component class="fieldset" ref="cardComponent" 
  :fonts="fonts" 
  :styles="styles" 
  :locale="locale" 
  :classes="classes" 
  :icon="icon"
  :placeholder="placeholder" 
></card-component>

Attaching event listeners

The following events listeners can be attached to card component CardComponent

  • ready
  • focus
  • blur
  • change

Example

<card-component class="fieldset" ref="cardComponent" 
  @ready="onReady"
  @change="onChange"
  @focus="onFocus"
  @blur="onBlur"
></card-component>

Card Field Components

The following props can be passed to the field Components CardNumber, CardExpiry, CardCVV

placeholder
String
Placeholder text for corresponding input field
style
Object Hide properties
Inline styles that needs to be applied to all input fields.
base
Object View properties
Pass the set of css properties that needs to be applied on default state.
empty
Object View properties
Pass the set of css properties that needs to be applied on empty state
invalid
Object View properties
Pass the set of css properties that needs to be applied on invalid state

Example

<card-number class="fieldset"
  :styles="styles" 
  :classes="classes" 
  :placeholder="placeholder" 
></card-number>

Attaching event listeners

The following events listeners can be attached to card fields

  • ready
  • focus
  • blur
  • change

Example

<card-number class="fieldset"
  @ready="onReady"
  @change="onChange"
  @focus="onFocus"
  @blur="onBlur"
></card-number>