Frontend Capabilities

# API Reference

This section provides details about various functions of the payment method helpers.

# canonicalUrl: https://www.chargebee.com/checkout-portal-docs/payment-handler-api-ref.html

# Payment Method Helpers

# Overview

This page documents the Payment Method Helpers API, which provides methods to handle payment authorization flows for various payment methods including cards, bank transfers, and digital wallets. Payment method helpers initiate the payment process and guide users through payment authorization.

# Prerequisites

Before using the Payment Method Helpers API, ensure you have initialized Chargebee.js in your application.

# Card payments

# 3DS handler

The 3DS handler object created using the create3DSHandler() method provides methods to manage 3D Secure (3DS) authentication flows for card payments.

# setPaymentIntent()

Sets the payment intent for the 3DS handler. The paymentIntent must be created on your server side. The payment intent contains information about the payment gateway and the amount to be charged. If you're using the payment gateway's JavaScript library alongside this module, pass the gateway JavaScript instance to this method as for internal 3DS flow handling.

# Syntax
threeDSHandler.setPaymentIntent(paymentIntent, options);
1
# Parameters
DETAILS
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
# Return value

None.

# Example
chargebee.load3DSHandler().then(threeDSHandler => {
  // Set the payment intent.
  threeDSHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});
1
2
3
4
5

# updatePaymentIntent()

Updates the payment intent attached to the 3DS handler. Use this method when the payment amount changes due to user interaction (for example, applying a discount coupon or adding tax). Make an API call to your server to update the payment intent (opens new window), then pass the updated payment intent to this method.

# Syntax
threeDSHandler.updatePaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let threeDSHandler;
chargebee.load3DSHandler().then(threeDSPaymentHandler => {
  threeDSHandler = threeDSPaymentHandler;
  // Set the payment intent.
  threeDSHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function updatePaymentIntent() {
  // Make an API call to your server to update the payment intent
  // using Chargebee's Update Payment Intent API.
  return updateIntentApi().then(updatedIntent => {
    return updatedIntent;
  });
}

function onApplyCoupon() {
  // Handle estimate amount change.
  updatePaymentIntent().then(paymentIntent => {
    // Set the updated payment intent to 3DS handler.
    threeDSHandler.updatePaymentIntent(paymentIntent);
  });
}

function onSubmit() {
  return threeDSHandler.handleCardPayment();
}
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

# getPaymentIntent()

Retrieves the payment intent object currently attached to the 3DS handler instance.

# Syntax
threeDSHandler.getPaymentIntent();
1
# Return value

Returns the payment intent object.

# handleCardPayment()

Initiates the 3DS flow for the card details entered. After successful 3DS authorization, the payment intent is marked as authorized.

Payment intent required

A payment intent must be created and configured before using this method. Learn more.

Cross-currency transactions

For cross-currency transactions from INR to another currency (for example, USD payment using an INR card), the following values are required:

  • plan: Name or description of the product.
  • customerBillingAddress: Customer billing address.
  • shippingAddress: Shipping address.
# Syntax
threeDSHandler.handleCardPayment(paymentInfo, callbacks);
1
# Parameters
DETAILS
paymentInfo
Object Hide properties
Card details collected or payment tokens can be passed here. Additionally, billing details can also be passed.
element
Object
Instance of gateway card component used can be passed here. For example: Adyen web components.
card
Object Hide properties
Card details.
number
String Required
Credit card number.
expiryMonth
String Required
Card expiration month.
expiryYear
String Required
Card expiration year.
cvv
String Required
CVV of card.
preferredScheme
String
Customer's preferred scheme for co-branded cards.
firstName
String Required if Worldpay gateway is used
First name of the customer.
lastName
String
Last name of the customer.
tokenizer
Function
A function that returns a gateway's card temp token.
cbToken
String
Chargebee's temporary token.
additionalData
Object Hide properties
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.
document
Object Required if EBANX or dLocal gateway is used Hide properties
The document details (e.g., national IDs or passports) used for document verification and payment processing by EBANX and dLocal.
number
String
The document number.
type
String
The type of document. Refer to the EBANX table or dLocal table below for the possible values.
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.
# Return value

Returns a promise that resolves to an authorized payment intent object.

# Example
let threeDSHandler;
chargebee.load3DSHandler().then(threeDSPaymentHandler => {
  threeDSHandler = threeDSPaymentHandler;
  // Set the payment intent
  threeDSHandler.setPaymentIntent(paymentIntent);
  // Additional logic here
});

function onSubmit() {
  return threeDSHandler.handleCardPayment().then(authorizedPaymentIntent => {
    // Make an API call to your server to use the authorized payment intent
    // to create a subscription.
    return createSubscriptionApi(authorizedPaymentIntent.id);
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# cancel()

Cancels an ongoing 3DS flow. The transaction is canceled with the gateway, and the payment attempt is marked as refused with an authentication failed status.

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

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

Call this method after invoking handleCardPayment() while a 3DS transaction is in progress. This method does not cancel an authorized payment intent.

# Syntax
threeDSHandler.cancel();
1
# Return value

Returns a promise.

# Example
let threeDSHandler = chargebee.create3DSHandler();
threeDSHandler
  .handleCardPayment(
    {
      card: {
        firstName: "John",
        lastName: "Doe",
        number: "4111111111111111",
        cvv: "123",
        expiryMonth: "12",
        expiryYear: "2025",
      },
    },
    {
      challenge: (redirect_url) => {
        // Open this redirect URL in a popup window.
      },
    }
  )
  .then((intent) => {
    console.log("Payment authorized successfully.");
  })
  .catch((error) => {
    console.error("Payment authorization failed:", 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

# Bancontact payment handler

The Bancontact payment handler object created using the load() method provides methods to manage Bancontact payment flows.

# getPaymentIntent()

Retrieves the payment intent attached to the payment method handler object.

# Syntax
bancontactHandler.getPaymentIntent();
1
# Return value

Returns the payment intent object.

# setPaymentIntent()

Attaches a payment intent to the payment method handler object. The payment intent contains information about the gateway and the payment.

# Syntax
bancontactHandler.setPaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let bancontactHandler;
chargebee.load('bancontact').then(_bancontactHandler => {
  bancontactHandler = _bancontactHandler;
  // Set the payment intent
  bancontactHandler.setPaymentIntent(paymentIntent);
  // Additional logic here
});
1
2
3
4
5
6
7

# updatePaymentIntent()

Updates the payment intent attached to the payment method handler object. Use this method after making changes to the payment intent.

# Syntax
bancontactHandler.updatePaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let bancontactHandler;
chargebee.load('bancontact').then(_bancontactHandler => {
  bancontactHandler = _bancontactHandler;
  // Set the payment intent.
  bancontactHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function onApplyCoupon() {
  // Make an API call to your server to update the payment intent with the new amount.
  updatePaymentIntentApi().then(updatedPaymentIntent => {
    // Set the updated payment intent.
    bancontactHandler.updatePaymentIntent(updatedPaymentIntent);
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.

# Syntax
bancontactHandler.handlePayment(paymentInfo, callbacks);
1
# Parameters
DETAILS
paymentInfo
Object View properties
Transaction-related information can be passed here.
callbacks
Object View properties
Callback that can be passed during the payment process.
# Return value

Returns a promise that resolves to a payment intent object after successful payment authorization.

# Example
DETAILS

For Adyen Card Components

bancontactHandler.handlePayment(
  {
    element: cardElement,
  },
  {
    success: function (paymentIntent) {
      console.log("Payment successful: ", paymentIntent);
    },
    error: function (error) {
      console.log("Payment failed: ", error);
    },
  }
);
1
2
3
4
5
6
7
8
9
10
11
12
13

For raw card details

bancontactHandler.handlePayment(
  {
    card: {
      number: "6703444444444449",
      expiryMonth: "12",
      expiryYear: "2025",
    },
  },
  {
    success: function (paymentIntent) {
      console.log("Payment successful: ", paymentIntent);
    },
    error: function (error) {
      console.log("Payment failed:", error);
    },
  }
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Wallet-based payments

# PayPal payment handler

The PayPal payment handler object can be created by loading the payment method using a Chargebee instance.

# getPaymentIntent()

Retrieves the payment intent attached to the payment method handler object.

# Syntax
payPalHandler.getPaymentIntent();
1
# Return value

Returns the payment intent object.

# Example
let paypalHandler;
chargebee.load('paypal').then(_paypalHandler => {
  paypalHandler = _paypalHandler;
  // Set the payment intent
  paypalHandler.setPaymentIntent(paymentIntent);
  // Additional logic here
});

function onClick() {
  paypalHandler.getPaymentIntent();
}
1
2
3
4
5
6
7
8
9
10
11

# setPaymentIntent()

Sets the payment intent for payment processing.

# Syntax
paypalHandler.setPaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let paypalHandler;
chargebee.load('paypal').then(_paypalHandler => {
  paypalHandler = _paypalHandler;
  // Set the payment intent.
  paypalHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});
1
2
3
4
5
6
7

# updatePaymentIntent()

Updates the payment intent attached to the payment method handler object.

# Syntax
paypalHandler.updatePaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let paypalHandler;
chargebee.load('paypal').then(_paypalHandler => {
  paypalHandler = _paypalHandler;
  // Set the payment intent.
  paypalHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function onUpdateCart() {
  // Make an API call to your server to update the payment intent.
  updatePaymentIntent().then(paymentIntent => {
    // Set the updated payment intent.
    paypalHandler.updatePaymentIntent(paymentIntent);
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# mountPaymentButton()

Mounts the PayPal payment button to the DOM.

# Syntax
paypalHandler.mountPaymentButton(selector, options);
1
# Parameters
DETAILS
selector
String Required
A valid CSS Selector for the element where the payment button should be mounted.
options
Object View properties
Options for PayPal button.
# Return value

Returns a promise that resolves after successfully mounting the PayPal button.

# Example
let paypalHandler;
chargebee.load("paypal").then((_paypalHandler) => {
  paypalHandler = _paypalHandler;
  // Set the payment intent.
  paypalHandler.setPaymentIntent(paymentIntent);

  // Mount the button to the DOM.
  return paypalHandler.mountPaymentButton("#button-holder");
});
1
2
3
4
5
6
7
8
9

# handlePayment()

Waits for payment processing to complete the transaction.

# Syntax
paypalHandler.handlePayment(callbacks);
1
# Parameters
DETAILS
callbacks
Object View properties
Callback that can be passed during the payment process.
# Return value

Returns a promise that resolves to a payment intent object after successful payment authorization.

# Example
let paypalHandler;
chargebee
  .load("paypal")
  .then((_paypalHandler) => {
    paypalHandler = _paypalHandler;
    // Set the payment intent.
    paypalHandler.setPaymentIntent(paymentIntent);

    // Mount the button to the DOM.
    return paypalHandler.mountPaymentButton("#button-holder");
  })
  // Wait for payment authorization to complete.
  .then(() => paypalHandler.handlePayment())
  .then((authorizedPaymentIntent) => {
    // Use the authorized payment intent to create a subscription.
    createSubscription(authorizedPaymentIntent);
  });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Google Pay payment handler

# getPaymentIntent()

Retrieves the payment intent attached to the Google Pay payment handler.

# Syntax
googlePayHandler.getPaymentIntent();
1
# Return value

Returns the payment intent object.

# setPaymentIntent()

Sets the payment intent for payment processing.

# Syntax
googlePayHandler.setPaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
chargebee.load('google-pay').then(googlePayHandler => {
  googlePayHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});
1
2
3
4

# updatePaymentIntent()

Updates the payment intent attached to the payment method handler object.

# Syntax
googlePayHandler.updatePaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let googlePayHandler;
chargebee.load('google-pay').then(_googlePayHandler => {
  googlePayHandler = _googlePayHandler;
  // Set the payment intent.  
  googlePayHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function onUpdateCart() {
  // Make an API call to your server to update the payment intent.
  updatePaymentIntent().then(paymentIntent => {
    // Set the updated payment intent.
    googlePayHandler.updatePaymentIntent(paymentIntent);
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# mountPaymentButton()

Mounts the Google Pay button to the DOM.

# Syntax
googlePayHandler.mountPaymentButton(selector, buttonOptions, paymentOptions);
1
# Parameters
DETAILS
selector
String Required
A valid CSS Selector for the element where the payment button should be mounted.
buttonOptions
Object Hide properties
Button options available for customizing Google Pay button. Learn more about supported button options for Google Pay.
buttonColor
String
Color of the Google Pay button.
Allowed Values:
default
black
white
buttonType
String
Type of the Google Pay button.
Allowed Values:
long
short
book
buy
checkout
donate
order
pay
plain
subscribe
buttonSizeMode
String
Button size options.
Allowed Values:
static
fill
buttonLocale
String
Locale options for the Google Pay Button.
paymentOptions
Object Hide properties
Config for Google Pay.
requestPayerEmail
Boolean
Set this flag to true, to return payer email after payment authorization.
requestBillingAddress
Boolean
Set this flag to true, to return billing address after payment authorization.
requestShippingAddress
Boolean
Set this flag to true, to return shipping address after payment authorization.
# Return value

Returns a promise that resolves after successfully mounting the payment button.

# Example
chargebee.load("google-pay").then((googlePayHandler) => {
  // Set the payment intent.
  googlePayHandler.setPaymentIntent(paymentIntent);
  return googlePayHandler.mountPaymentButton("#button-holder");
});
1
2
3
4
5

# handlePayment()

Waits for payment authorization to complete.

# Syntax
googlePayHandler.handlePayment(callbacks);
1
# Parameters
DETAILS
callbacks
Object Hide properties
Callback that can be passed during the payment process.
error
Function
Triggers when there is an error during the transaction.
success
Function
Triggers when transaction is successfully completed.
change
Function
Triggers when there is a change in the transaction state.
# Return value

Returns a promise that resolves to a payment intent object after successful payment authorization.

# Example
let googlePayHandler;
chargebee
  .load("google-pay")
  .then((_googlePayHandler) => {
    googlePayHandler = _googlePayHandler;
    // Set the payment intent.
    googlePayHandler.setPaymentIntent(paymentIntent);
    return googlePayHandler.mountPaymentButton("#button-holder");
  })
  .then(() => googlePayHandler.handlePayment())
  .then((paymentIntent) => {
    // Use payment intent to create a subscription
  });
1
2
3
4
5
6
7
8
9
10
11
12
13

# Apple Pay payment handler

# canMakePayments()

Checks whether the device supports the Apple Pay payment method.

# Syntax
applePayHandler.canMakePayments();
1
# Return value

Returns a boolean value indicating Apple Pay support.

# Example
const isApplePayAvailable = applePayHandler.canMakePayments();
1

# applePayCapabilities()

Checks whether the device supports Apple Pay and whether the user's Apple Wallet contains an active payment method eligible for web payments.

Call this method before calling mountPaymentButton() to determine if Apple Pay can be used on the current device.

# Syntax
applePayHandler.applePayCapabilities();
1
# Return value

Returns a promise that resolves to a PaymentCredentialStatusResponse (opens new window) object.

# Example
applePayHandler.applePayCapabilities().then(capabilities => {
  switch (capabilities.paymentCredentialStatus) {
    case "paymentCredentialsAvailable":
      // Display an Apple Pay button and offer Apple Pay as the primary payment option. 
      break;
    case "paymentCredentialStatusUnknown":
      // Display an Apple Pay button and offer Apple Pay as a possible payment option.
      break;
    case "paymentCredentialsUnavailable":
      // Offer Apple Pay as a payment option, but don't make it the default payment option.
      break;
    case "applePayUnsupported":
      // Don't display an Apple Pay button or offer Apple Pay as a payment option.
      break;
  }
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# mountPaymentButton()

Mounts the Apple Pay button to the DOM.

Note

Check whether the device supports Apple Pay using the applePayCapabilities() method before calling this method.

# Syntax
applePayHandler.mountPaymentButton(selector, options);
1
# Parameters
DETAILS
selector
String Required
A valid CSS Selector for the element where the payment button should be mounted.
options
Object View properties
Other options and button customizations.
# Return value

Returns a promise that resolves after successfully mounting the payment button.

# Example
applePayHandler.mountPaymentButton("#applepay-button", {
  locale: "en_US",
  buttonColor: "black",
  buttonType: "plain",
  recurringPaymentRequest: {
    paymentDescription: "Premium Membership Subscription",
    regularBilling: {
      label: "Monthly Subscription",
      amount: "9.99"
    },
    trialBilling: {
      label: "Free Trial - First Month",
      amount: "0.00"
    },
    billingAgreement: "You authorize monthly charges for the Premium Membership.",
    managementURL: "https://example.com/account/subscription",
    tokenNotificationURL: "https://example.com/api/payment/token-notify"
  }
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.

# Syntax
applePayHandler.handlePayment(callbacks);
1
# Parameters
DETAILS
callbacks
Object View properties
Callbacks that can be passed during the payment process.
# Return value

Returns a promise that resolves to a payment intent object after successful payment authorization.

# Example
applePayHandler
  .handlePayment()
  .then((paymentIntent) => {
    console.log("Payment successful", paymentIntent);
    // Use the authorized payment intent to create a subscription.
  })
  .catch((error) => {
    console.log("Payment failed", error);
  });
1
2
3
4
5
6
7
8
9

# Payconiq by Bancontact handler

The Payconiq by Bancontact payment handler (opens new window) integrates the Payconiq by Bancontact payment method on your site or application.

The Payconiq by Bancontact payment method handler object can be created using the load() method of a Chargebee instance.

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.

# Syntax
chargebee.handlePayment("payconiq_by_bancontact", options);
1
# Parameters
DETAILS
paymentIntent
Function
Function that returns a payment intent object created on your server side.
renderInfo
Object View properties
Configuration options for customizing the Payconiq by Bancontact payment interface.
callbacks
Object View properties
Callback that can be passed during the payment process.
# Return value

Returns a promise that resolves to a payment intent object after successful payment authorization.

# Example
chargebee.load("payconiq_by_bancontact").then(() => {
  chargebee.handlePayment("payconiq_by_bancontact", {
    paymentIntent: () => {
      return createPaymentIntent();
    },
    renderInfo: {
      heading: "Scan QR code.",
      timerLabel: "This QR code is valid for {time}.", // Timer will be reflected in place of {time}.
      timerDurationSeconds: 15 * 60, // 15 minutes.
      buttonText: "Continue to Payconiq by Bancontact.",
    }
  }).then(intent => {
    // Payment intent is pending - customer needs to scan QR code
    return createSubscription(intent.id);
  }).catch(error => {
    console.error('Payment failed:', error);
  });
});

function createSubscription(paymentIntentId) {
  return fetch('/subscriptions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      paymentIntentId: paymentIntentId,
      plan_id: 'pro_plan',
      plan_quantity: 1,
      billingAddress: {
        // Add billing address details. 
      },
      customer: {
        // Add customer details.
      }
    })
  }).then(response => response.json());
}
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

# Venmo handler

The Venmo payment handler (opens new window) integrates the Venmo payment method on your site or application.

The Venmo payment method handler object can be created using the load() method of a Chargebee instance.

# getPaymentIntent()

Retrieves the payment intent attached to the payment method handler object.

Retrieve billing address from Venmo

When using the Braintree payment gateway for Venmo payments (opens new window), the payment_intent object returned by default does not include billing_address. This information may be required for tasks such as calculating sales tax. To ensure that payer_info.billing_address is included in the payment_intent object, enable Enriched Customer Data (ECD) (opens new window) in the Braintree Control Panel. Once enabled, Chargebee automatically includes this customer detail.

# Syntax
venmoHandler.getPaymentIntent();
1
# Return value

Returns the payment intent object.

# Example
let venmoHandler;
chargebee.load('venmo').then(_venmoHandler => {
  venmoHandler = _venmoHandler;
  // Set the payment intent.
  venmoHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function onClick() {
  venmoHandler.getPaymentIntent();
}
1
2
3
4
5
6
7
8
9
10
11

# setPaymentIntent()

Associates a payment intent with the Venmo payment method handler for payment processing.

# Syntax
venmoHandler.setPaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let venmoHandler;
chargebee.load('venmo').then(_venmoHandler => {
  venmoHandler = _venmoHandler;
  // Set the payment intent
  venmoHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});
1
2
3
4
5
6
7

# updatePaymentIntent()

Updates the payment intent associated with the Venmo payment method handler.

# Syntax
venmoHandler.updatePaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let venmoHandler;
chargebee.load('venmo').then(_venmoHandler => {
  venmoHandler = _venmoHandler;
  // Set the payment intent.
  venmoHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function onUpdateCart() {
  // Make an API call to your server to update the payment intent.
  updatePaymentIntent().then(paymentIntent => {
    // Set the updated payment intent.
    venmoHandler.updatePaymentIntent(paymentIntent);
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# mountPaymentButton()

Mounts the Venmo payment button to the DOM.

# Syntax
venmoHandler.mountPaymentButton(selector);
1
# Parameters
DETAILS
selector
String Required
A valid CSS Selector for the element where the payment button should be mounted.
# Return value

Returns a promise that resolves after successfully mounting the Venmo payment button.

# Example
let venmoHandler;
chargebee.load("venmo").then((_venmoHandler) => {
  venmoHandler = _venmoHandler;
  // Set the payment intent.
  venmoHandler.setPaymentIntent(paymentIntent);

  // Mount the button to the DOM.
  return venmoHandler.mountPaymentButton("#button-holder");
});
1
2
3
4
5
6
7
8
9

# handlePayment()

Waits for payment processing to complete the transaction.

# Syntax
venmoHandler.handlePayment(callbacks);
1
# Parameters
DETAILS
callbacks
Object View properties
Callback that can be passed during the payment process.
# Return value

Returns a promise that resolves to a payment intent object after successful payment authorization.

# Example
let venmoHandler;
chargebee
  .load("venmo")
  .then((_venmoHandler) => {
    venmoHandler = _venmoHandler;
    // Set the payment intent.
    venmoHandler.setPaymentIntent(paymentIntent);

    // Mount the button to the DOM.
    return venmoHandler.mountPaymentButton("#button-holder");
  })
  // Wait for payment authorization to complete.
  .then(() => venmoHandler.handlePayment())
  .then((authorizedPaymentIntent) => {
    // Use the authorized payment intent to create a subscription.
    createSubscription(authorizedPaymentIntent);
  });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Bank-based payments

# Initiating bank payments

All bank-based payment method transactions are initiated using the chargebee.handlePayment() method.

Note

This workflow is common for all Chargebee.js-supported bank payment methods.

Supported payment methods:

  • iDEAL
  • SOFORT
  • Giropay
  • dotpay
  • Netbanking e-Mandate
  • Direct debit

# handlePayment()

Initiates the payment process. This method should be invoked from Chargebee instance object. Upon initiation, user maybe redirected to the bank’s webpage for authorizing the payment.

# Syntax
cbInstance.handlePayment(paymentMethodType, paymentOptions);
1
# Parameter
paymentMethodType
Enum Required
Name of the payment method type.
Allowed Values:
ideal
sofort
bancontact
giropay
dotpay
netbanking_emandates
direct_debit
paymentOptions
Object View properties
Options for the payment method type.
# Return value

A promise that resolves to an authorized payment intent object.

# iDEAL payment handler

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.

Learn more.

# Example
chargebee.handlePayment("ideal", {
  paymentIntent: () => {
    // Make a call to your server to create a Chargebee payment intent.
    return createPaymentIntent();
  },
  callbacks,
  paymentInfo: {
    userName: "Jane Doe",
    userEmail: "janedoe@example.com",
  }
});
1
2
3
4
5
6
7
8
9
10
11

# mountBankList() deprecated

Deprecation notice

This method is deprecated and will no longer be supported after April 1, 2025.

To ensure continued functionality, upgrade to the latest version of the integration.

Attaches a dropdown element to the page that displays the list of banks supported by the gateway.

Note

For iDEAL payments, Adyen Web Components can be used as an alternative to mountBankList(). After selecting a bank in the Adyen component, pass the information to the paymentInfo parameter in the handlePayment() method.

# Syntax
<label class="ex2-field">
  <span id="dropdown-element" class="ex2-input"></span>
</label>
1
2
3
idealPaymentHandler.mountBankList(selector, options);
1
# Parameters
DETAILS
selector
String Required
A valid CSS Selector for the element where the payment button should be mounted.
options
Object Hide properties
Configuration options
locale
String
currency
String
Currency code
gateway_account_id
String
Chargebee gateway account ID
style
Object
Style customizations for bank drop-down component
# Return value

Returns a promise that resolves after successfully mounting the bank list.

# Example
chargebee.load("ideal").then((idealHandler) => {
  // Mount bank list.
  return idealHandler.mountBankList("#drop-down-container", {
    currency: "USD",
  });
});
1
2
3
4
5
6

# getSelectedBank() deprecated

Deprecation notice

This method is deprecated and will no longer be supported after April 1, 2025.

To ensure continued functionality, upgrade to the latest version of the integration.

Retrieves the details of the bank selected by the user from the dropdown element.

# Syntax
idealHandler.getSelectedBank();
1
# Return value

Returns an object containing the details of the selected bank:

{
  id: 'bank-id',
  name: 'Name of the bank.'
}
1
2
3
4

# SOFORT payment handler

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.

Learn more.

# Example
chargebee.handlePayment("sofort", {
  paymentIntent: () => {
    // Make an API call to the server to create a payment intent.
    return createPaymentIntent();
  },
  paymentInfo: {
    userName: "John Doe",
    userEmail: "johndoe@example.com",
    country: "US", // Country code.
  },
});
1
2
3
4
5
6
7
8
9
10
11

# Giropay payment handler

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.

Learn more.

# Example
chargebee.handlePayment("giropay", {
  paymentIntent: () => {
    // Make an API call to the server to create a payment intent.
    return createPaymentIntent();
  },
});
1
2
3
4
5
6

# DotPay payment handler

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create invoices.

Learn more.

# Example
chargebee.handlePayment("dotpay", {
  paymentIntent: () => {
    // Make an API call to the server to create a payment intent.
    return createPaymentIntent();
  },
});
1
2
3
4
5
6

# mountBankList()

Mounts a dropdown element that displays the list of banks supported by the gateway. Pass the ID of the dropdown element where the bank list should be attached.

# Syntax
dotpayHandler.mountBankList(selector, options);
1
# Parameters
DETAILS
selector
String Required
A valid CSS Selector for the element where the payment button should be mounted.
options
Object Hide properties
Configuration options
locale
String
currency
String
Currency code
gateway_account_id
String
Chargebee gateway account ID
style
Object
Style customizations for bank drop-down component
# Return value

Returns a promise that resolves after successfully mounting the bank list to the DOM.

# Example
dotpayHandler.mountBankList("#dotpay", {
  currency: "USD",
  locale: "en_US",
  style: {
    base: {
      backgroundColor: "#fff",
      ":hover": {
        backgroundColor: "#f4f5f9",
      },
    },
  },
});
1
2
3
4
5
6
7
8
9
10
11
12

# getSelectedBank()

Retrieves the details of the bank selected by the user from the dropdown element.

# Syntax
dotpayHandler.getSelectedBank();
1
# Parameters
DETAILS
id
ID of the selected bank
name
Name of the selected bank. This will be optionally returned based on the gateway selected.
# Return value

Returns an object containing the details of the selected bank:

{
  id: 'bank-id',
  name: 'Name of the bank'
}
1
2
3
4

# Netbanking payment handler

# setPaymentIntent()

Sets the payment intent for the Netbanking handler. The payment intent contains information about the payment gateway and the amount to be charged.

# Syntax
netBankingHandler.setPaymentIntent(paymentIntent, options);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
chargebee.load('netbanking_emandates').then(netBankingHandler => {
  // Set the payment intent
  netBankingHandler.setPaymentIntent(paymentIntent);
  // Additional logic here
});
1
2
3
4
5

# updatePaymentIntent()

Updates the payment intent attached to the Netbanking handler. Use this method when the payment amount changes due to user interaction (for example, applying a discount coupon or adding tax). Make an API call to your server to update the payment intent (opens new window), then pass the updated payment intent to this method.

# Syntax
netBankingHandler.updatePaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let netBankingHandler;
chargebee.load('netbanking_emandates').then(netBankingPaymentHandler => {
  netBankingHandler = netBankingPaymentHandler;
  // Set the payment intent.
  netBankingHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function onCartUpdate() {
  // Make an API call to your server to update the payment intent with the revised amount.
  // using Chargebee's Update Payment Intent API.
  updateIntentApi().then(paymentIntent => {
    // Set the updated payment intent to the payment handler.
    netBankingHandler.updatePaymentIntent(paymentIntent);
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# getPaymentIntent()

Retrieves the payment intent object currently attached to the Netbanking handler instance.

# Syntax
netBankingHandler.getPaymentIntent();
1
# Return value

Returns the payment intent object.

# fetchBankList()

Fetches the list of banks supported by the payment gateway for Netbanking.

# Syntax
netBankingHandler.fetchBankList(options);
1
# Parameters
DETAILS
options
Object Hide properties
currency
String Required
Currency code of the payment currency. If not provided, currency code from Payment Intent will be used.
# Return value

Returns a promise that resolves to an array of bank objects. Each object contains the id and name of the respective bank:

[
  {
    id: "bank_id",
    name: "Name of the bank.",
  },
]
1
2
3
4
5
6
# Example
let netBankingHandler;
chargebee
  .load("netbanking_emandates")
  .then((netBankingPaymentHandler) => {
    netBankingHandler = netBankingPaymentHandler;
    // Set the payment intent.
    netBankingHandler.setPaymentIntent(paymentIntent);

    const options = {
      currency: paymentIntent.currency_code || "INR",
    };
    return netBankingHandler.fetchBankList(options);
  })
  .then((bankList) => {
    // Returns list of supported banks.
  });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create invoices.

Learn more.

# Example
chargebee
  .load("netbanking_emandates")
  .then((netBankingHandler) => {
    netBankingHandler.setPaymentIntent(intent);
    return netBankingHandler.fetchBankList({
      currency: paymentIntent.currency_code || "INR",
    });
  })
  .then((bankList) => {
    // Display list of supported banks for Netbanking.
  });

function onSubmit() {
  // Collect the required parameters from the user before initiating payment
  const paymentInfo = {
    customer: {
      firstName: "John",
      lastName: "Doe",
      email: "johndoe@example.com",
      phone: "+1XXXXXXXXXX",
    },
    bankAccount: {
      bank: "Bank Name",
      beneficiaryName: "Acme Pvt Ltd.",
      accountNumber: "XXXXXXXXXXXX",
      accountType: "current",
      ifscCode: "XXXXXXXX",
    },
  };
  return chargebee.handlePayment("netbanking_emandates", {
    paymentInfo: paymentInfo,
  });
}
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

# UPI payment handler

# setPaymentIntent()

Sets the payment intent for the UPI handler. The payment intent contains information about the payment gateway and the amount to be charged.

# Syntax
upiHandler.setPaymentIntent(paymentIntent, options);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
chargebee.load('upi').then(upiHandler => {
  // Set the payment intent
  upiHandler.setPaymentIntent(paymentIntent);
  // Additional logic here
});
1
2
3
4
5

# updatePaymentIntent()

Updates the payment intent attached to the UPI handler. Use this method when the payment amount changes due to user interaction (for example, applying a discount coupon or adding tax). Make an API call to your server to update the payment intent (opens new window), then use this method to set the updated payment intent to the UPI payment handler.

# Syntax
upiHandler.updatePaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let upiHandler;
chargebee.load('upi').then(upiPaymentHandler => {
  upiHandler = upiPaymentHandler;
  // Set the payment intent.
  upiHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function onCartUpdate() {
  // Make an API call to your server to update the payment intent with the revised amount.
  // using Chargebee's Update Payment Intent API.
  updateIntentApi().then(paymentIntent => {
    // Set the updated payment intent to the payment handler.
    upiHandler.updatePaymentIntent(paymentIntent);
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# getPaymentIntent()

Retrieves the payment intent object currently attached to the UPI handler.

# Syntax
upiHandler.getPaymentIntent();
1
# Return value

Returns the payment intent object.

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.

# Syntax
upiHandler.handlePayment(paymentInfo, callbacks);
1
# Parameters
DETAILS
paymentInfo
Object View properties
Transaction-related information can be passed here.
callbacks
Object View properties
Callback that can be passed during the payment process.
# Return value

Returns a promise that resolves to an authorized payment intent object.

# Example
let upiHandler;
chargebee.load("upi").then((paymentHandler) => {
  upiHandler = paymentHandler;
  upiHandler.setPaymentIntent(intent);
});

function onSubmit() {
  // Collect the required parameters from the user before initiating payment.
  const paymentInfo = {
    customer: {
      firstName: "John",
      lastName: "Kennedy",
      email: "john@example.com",
      phone: "XXXXXXXXXX",
    },
    vpa: "john@bank", // Customer UPI ID.
  };

  // Show a loading screen or timer to the user until the UPI payment transaction is authorized.
  return upiHandler
    .handlePayment(paymentInfo)
    .then((paymentIntent) => {
      // Use the authorized payment intent to create a subscription.
      return createSubscriptionApi(paymentIntent.id);
    })
    .catch((error) => {
      // Transaction failed.
      console.error("Payment failed:", error);
    });
}
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

# Direct Debit handler

# setPaymentIntent()

Sets the payment intent for the Direct Debit handler. The payment intent contains information about the payment gateway and the amount to be charged.

# Syntax
directDebitHandler.setPaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
chargebee.load('direct_debit').then(directDebitHandler => {
  // Set the payment intent.  
  directDebitHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});
1
2
3
4
5

# updatePaymentIntent()

Updates the payment intent attached to the Direct Debit handler. Use this method when the payment amount changes due to user interaction (for example, applying a discount coupon or adding tax). Make an API call to your server to update the payment intent (opens new window), then pass the updated payment intent to this method.

# Syntax
directDebitHandler.updatePaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let directDebitHandler;
chargebee.load('direct_debit').then(directDebitPaymentHandler => {
  directDebitHandler = directDebitPaymentHandler;
  // Set the payment intent.
  directDebitHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function onCartUpdate() {
  // Make an API call to your server to update the payment intent with the revised amount.
  // using Chargebee's Update Payment Intent API.
  updateIntentApi().then(paymentIntent => {
    // Set the updated payment intent to the payment handler.
    directDebitHandler.updatePaymentIntent(paymentIntent);
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create invoices.

Learn more.

# Example
chargebee.load("direct_debit").then(directdebitHandler => {
  createPaymentIntent().then((paymentIntent) => {
    directdebitHandler.setPaymentIntent(paymentIntent);
    const paymentInfo = {
      plaid: {
        userId: "123",
      }
    };
    directdebitHandler.handlePayment(paymentInfo).then(paymentIntent => {
      // Payment intent is authorized.
      return fetch('/subscriptions', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          paymentIntentId: paymentIntent.id,
          plan_id: 'pro_plan',
          plan_quantity: 1,
          billingAddress: {
            // Provide billing address.
          },
          customer: {
            // Provide customer details if the subscription is to be created for an existing customer in Chargebee
          }
        })
      }).then(response => response.json());
    }).catch(error => {
      // Payment intent is not authorized
      console.error("Payment failed:", error);
    });
  });
});
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

# Voucher-based payments

# Boleto handler

The Boleto payment handler object can be created by loading the payment method using a Chargebee instance.

# setPaymentIntent()

Sets the payment intent for the Boleto handler. The payment intent contains information about the payment gateway and the amount to be charged.

# Syntax
boletoHandler.setPaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
chargebee.load('boleto').then(boletoHandler => {
  // Set the payment intent.  
  boletoHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});
1
2
3
4
5

# updatePaymentIntent()

Updates the payment intent attached to the Boleto handler. Use this method when the payment amount changes due to user interaction (for example, applying a discount coupon or adding tax). Make an API call to your server to update the payment intent (opens new window), then pass the updated payment intent to this method.

# Syntax
boletoHandler.updatePaymentIntent(paymentIntent);
1
# Parameters
DETAILS
paymentIntent
Object Required
Payment Intent object
# Return value

None.

# Example
let boletoHandler;
chargebee.load('boleto').then(boletoPaymentHandler => {
  boletoHandler = boletoPaymentHandler;
  // Set the payment intent.
  boletoHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});

function onCartUpdate() {
  // Make an API call to your server to update the payment intent with the revised amount.
  // using Chargebee's Update Payment Intent API.
  updateIntentApi().then(paymentIntent => {
    // Set the updated payment intent to the payment handler.
    boletoHandler.updatePaymentIntent(paymentIntent);
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# handlePayment()

Initiates the payment process. After successful authorization, the payment intent is marked as authorized. After creating a subscription, you can use the authorized payment intent in Chargebee APIs to display the vouchers.

# Syntax
boletoHandler.handlePayment(paymentInfo, callbacks);
1
# Parameters
DETAILS
paymentInfo
Object View properties
Transaction-related information can be passed here.
callbacks
Object View properties
Callback that can be passed during the payment process.
# Return value

Returns an authorized payment intent object.

# Example
chargebee.load("boleto").then(boletoHandler => {
  createPaymentIntent().then((paymentIntent) => {
    boletoHandler.setPaymentIntent(paymentIntent);
    const paymentInfo = {
      customer: {
        firstName: "John",
        lastName: "Doe",
        email: "johndoe@example.com",
        phone: "+5511987654321"
      },
      billingAddress: {
        firstName: "John",
        lastName: "Doe",
        addressLine1: "Rua Exemplo 123",
        addressLine2: "Apt 45",
        city: "São Paulo",
        state: "SP",
        countryCode: "BR",
        zip: "01310-100"
      },
      taxId: "12345678901"
    };

    boletoHandler.handlePayment(paymentInfo).then(paymentIntent => {
      // Payment intent is authorized.
      return fetch('/subscriptions', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          paymentIntentId: paymentIntent.id,
          plan_id: 'pro_plan',
          plan_quantity: 1,
          billingAddress: {
            // Provide billing address.
          },
          customer: {
            // Provide customer details if the subscription is to be created for an existing customer in Chargebee.
          }
        })
      }).then(response => response.json());
    }).catch(error => {
      // Payment intent is not authorized.  
      console.error("Payment failed:", error);
    });
  });
});
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
43
44
45
46
47
48