Frontend Capabilities

# API Reference

This reference is for integrating "3DS helper module" into your application.

# Chargebee object

# init

This function is used to initialize Chargebee with your site, domain name. The 'chargebee instance' object returned as result of initialization is used to create 3DS handler object.

# Syntax

Chargebee.init(options);
1

# 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.
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.
  • Multiple Business Entities is currently in early access. Contact eap@chargebee.com to join the Early Adopter Program and enable this feature.

# Return value

Chargebee instance object

# Example

var cbInstance = Chargebee.init({
  site: "site-name", // your test site
  domain: "https://mybilling.acme.com", // this is an optional parameter.
});
1
2
3
4

# getInstance

This function will return 'chargebee instance' object.

# Syntax

Chargebee.getInstance();
1

# Return value

Chargebee instance object

Error will be thrown if instance is not created.

# Chargebee instance object

Chargebee instance is used to create 3DS handler object

# load3DSHandler

This function will load 3DS-helper module and will intialize 3DS handle object. You can use this approach or the above approach to load 3DS-helper module.

# Syntax

cbInstance.load3DSHandler();
1

# Return value

Promise that resolves 3DS handler object.

# Example

cbInstance.load3DSHandler().then((threeDSHandler) => {
  // your code here
});
1
2
3

# create3DSHandler

You can create a threeDS handler object using this method as well. But 3ds-handler module should be loaded prior to using this method.

# Return value

3DS handler object.

# Example

cbInstance.load("3ds-handler").then(() => {
  let threeDSHandler = cbInstance.create3DSHandler();
  // Your code here
});
1
2
3
4

# 3DS Handler Instance

3DS handler instance is used to handle 3DS authorization flow.

# setPaymentIntent

Use this function to set paymentIntent that was created at your server side. The paymentIntent will contain information about the payment gateway and the amount that needs to be charged. In case you are using the respective gateway's JS library along with this module, pass the gateway JS instance in this method. This gateway JS instance will internally be used for handling 3DS flow.

# Syntax

threeDSHandler.setPaymentIntent(paymentIntent, options);
1

# Parameters

paymentIntent
Object Required
Payment Intent object
options
Object Hide properties
stripe
Object
Stripe.js instance. Learn more about creating an instance of the Stripe object.
braintree
Object
Braintree.js client instance
adyen
Object
Adyen.js checkout instance

# Example

cbInstance.load3DSHandler((threeDSHandler) => {
  // This payment intent can be loaded while rendering the page or via ajax call
  threeDSHandler.setPaymentIntent(paymentIntent);

  // In case you are using adyen web components, you can pass the adyen instance with this method,
  threeDSHandler.setPaymentIntent(paymentIntent, {
    adyen: adyenCheckoutInstance,
  });
});
1
2
3
4
5
6
7
8
9

# updatePaymentIntent

Whenever the amount that needs to charged changes with user interaction (discount coupon applied, tax), you can do an ajax call to your server to update the payment intent using this API (opens new window). This updated paymentIntent should then be passed to this function.

# Syntax

threeDSHandler.updatePaymentIntent(paymentIntent, options);
1

# Parameters

paymentIntent
Object Required
Payment Intent object

# Example

let threeDSHandler = cbInstance.create3DSHandler();
// This payment intent can be loaded while rendering the page or via ajax call
threeDSHandler.updatePaymentIntent(paymentIntent);
1
2
3

# getPaymentIntent

Returns the payment intent object that is currently set in the 3DS handler instance.

# Syntax

threeDSHandler.getPaymentIntent();
1

# Return value

paymentIntent object

# handleCardPayment

A paymentIntent needs to be created and setup before using this method. Click here to know more

Call this function to initiate 3DS flow for the entered card details. Based on the Issuing Bank and gateway settings, 3DS flow can be initiated or not. After a successful 3DS authorization, paymentIntent will be marked as authorized. This paymentIntent id can then be used to create subscriptions or create payment methods.

Only for 3DS Helper users
If the transaction is from INR to any other currency(eg. an USD payment made using an INR card), it is mandatory to pass two values:
  1. plan
  2. customerBillingAddress or shippingAddress

# Return value

Authorized paymentIntent object

# Syntax

threeDSHandler.handleCardPayment(paymentInfo, callbacks);
1

# Parameters

paymentInfo
Object View properties
Card details collected or payment tokens can be passed here. Additionally, billing details can also be passed.
callbacks
Object View properties
Callbacks to be used for this operation.

# Example

let threeDSHandler = cbInstance.create3DSHandler();
threeDSHandler.handleCardPayment(
  {
    card: {
      firstName: "First Name",
      lastName: "Last Name",
      number: "xxxx xxxx xxxx xxxx",
      cvv: "",
      expiryMonth: "10",
      expiryYear: "2019",
    },
    additionalData: {
      // you can pass additional information to improve the chances to do a frictionless authorization
      billingAddress: {
        firstName: "",
        lastName: "",
        phone: "",
        addressLine1: "",
        addressLine2: "",
        addressLine3: "",
        city: "",
        state: "",
        stateCode: "",
        countryCode: "",
        zip: "",
      },
      email: "john@example.com",
      phone: "",
    },
  },
  {
    change: function (intent) {
      // Triggers on each step transition
    },
    success: function (intent) {
      // Triggers when card is 3DS authorized
    },
    error: function (intent, error) {
      // Triggers when 3DS authorization fails
    },
  }
);
1
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

# cancel

Call this function to cancel an ongoing 3DS flow. The transaction is cancelled with the gateway, and the payment attempt is refused with authentication failed status.

An error is thrown if no payment intent is set, or if there is no ongoing 3DS transaction.

This cancel action is primarily used along with challenge callback implementation, where the 3DS redirection URL is provided.

This function has to be called, after the handleCardPayment method is called, while there is an ongoing 3DS transaction. This method does not cancel an authorized payment intent.

# Return value

Promise

# Syntax

threeDSHandler.cancel();
1

# Example

let threeDSHandler = cbInstance.create3DSHandler();
threeDSHandler
  .handleCardPayment(
    {
      card: {
        firstName: "First Name",
        lastName: "Last Name",
        number: "xxxx xxxx xxxx xxxx",
        cvv: "",
        expiryMonth: "10",
        expiryYear: "2019",
      },
    },
    {
      challenge: (redirect_url: string) => {
        // Open this redirect URL in a popup window
      },
    }
  )
  .then((intent) => {
    console.log("success");
  })
  .catch((error) => {
    console.error(error);
  });

function onCloseWindow() {
  threeDSHandler.cancel();
}
1
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

← Estimate Functions →