# How to Integrate

# Setting up Chargebee JS

# Inserting chargebee.js script in your application

Include the following script in your HTML page. You need to do this only once per page.

<script src="https://js.chargebee.com/v2/chargebee.js"></script>

# Initializing a Chargebee instance

Inside your JavaScript code, initialize chargebee with the publishable key (opens new window) once the page is loaded and get 'chargebee instance' object. This object is used further to create components.

Example:

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

1
2
3
4
5

Learn more about initializing a Chargebee instance.

Once you setup Chargebee JS, follow the below steps to complete integrating 3DS:

# Integrating 3D Secure

# Initialize and load 3DS helper module

Use the load3DSHandler method to load and initialize the 3DS Helper module. Then use the threeDSHandler to initiate 3DS flow.

let cbInstance = Chargebee.getInstance();
cbInstance.load3DSHandler().then((threeDSHandler) => {
  // your code here
});

1
2
3
4

# PaymentIntent Object

A paymentIntent should be created at your server using create paymentIntent API (opens new window) and returned to the client side. ThreeDS handler uses the created paymentIntent internally to perform 3DS authorization.

While creating the paymentIntent, you need to specify the amount that needs to be charged from the customer. You can also choose to specifiy which gateway needs to be used for this charge. If not mentioned, smart routing (opens new window) rules will be applied

You can use the update paymentIntent API (opens new window) to update the paymentIntent with different amount before its consumed. (Amount can change when tax is applied or when an end-user enters a discount coupon).

For authorizing a stored payment method, pass the amount and payment method's reference id (opens new window) while creating the payment intent.

TIP

In case there is no immediate charge, mention a default amount(specific to each gateway). This amount will be returned back to the customer after verification.

# Setting the Payment Intent to the 3DS Handler Instance

On the client side, set the created paymentIntent to the 3DSHandler using the setPaymentIntent method.

function createPaymentIntent() {
  // Create a payment intent at your server side
  // paymentIntent can either be prefetched while loading the HTML or via an ajax call
}

cbInstance.load3DSHandler().then((threeDSHandler) => {
  // Set the created paymentIntent
  threeDSHandler.setPaymentIntent(paymentIntent);

  // The paymentIntent can be updated whenever the amount gets changed
  threeDSHandler.updatePaymentIntent(paymentIntent);
});

1
2
3
4
5
6
7
8
9
10
11
12

Learn more about the supported parameters for setPaymentIntent method.

# Handling Card Payments Using 3DS

Let us see how card payments can be handled in Chargebee.js using 3DS.

# 3DS for a New Card

When the user attempts to checkout after entering card details, call handleCardPyament method for initiating 3DS flow.

Click here for a complete list of additional parameters that you can pass.

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 transaction
    },
  },
  {
    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

# 3DS for Existing Cards

Specify the payment methods's referenceId (opens new window) when creating the paymentIntent. Then, call the handleCardPayment method without passing any additional parameters.

threeDSHandler
  .handleCardPayment()
  .then((intent) => {
    // Call update subscription API / collect now API
  })
  .catch((error) => {
    // Handle error
  });

1
2
3
4
5
6
7
8

# Handling PaymentIntent for 3DS

After a 3DS flow is completed, the paymentIntent returned will be in authorized state, you can use this paymentIntent id for creating a subscription (opens new window), adding a payment source (opens new window), or collecting payment of an unpaid invoice (opens new window) that failed due to 3DS.

Follow the steps below to implement the RBI mandate using authorized payment intent.

Create paymentIntent API (opens new window) for the actual amount of subscription (use Estimate API (opens new window)).
Set the mandate object if there is a need to create the mandate.
Use the Authorized Payment Intent to create a subscription so that the mandate can get associated with the subscription.

TIP

If you use payment_intent to add a payment_method at the customer level separately and create a subscription using the existing payment_method without the Payment Intent flow, then the mandate will not associate with the Subscription.

# 3DS with challenge URL redirection

The handleCardPayment function also provides the ability to access the challenge URL without automatically presenting the challenge window to the user. In this workflow, the merchant is expected to present the challenge URL to the end-user using an iframe or a popup window.

The challenge URL can be accessed by implementing the challenge callback in the handleCardPayment method. The transaction proceeds in this workflow only if this callback is implemented.

When the challenge window is closed by the end-user. The merchant needs to call the cancel method to cancel the ongoing transaction. This will refuse the payment attempt, and the handleCardPayment function call is rejected with authentication failed payment attempt status.

Currently this workflow is supported by Adyen, Braintree and Stripe payment gateways.

← Overview Examples →