chargebee js

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, digital wallets, and cryptocurrencies. 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.

Tutorials

For a step-by-step integration, see the Payment Method Helper tutorials.

Card payments

3DS handler

The 3DS handler object created using the load3DSHandler() 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 using the Create payment intent API. 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, you pass the gateway JavaScript instance to this method.

Syntax
threeDSHandler.setPaymentIntent(paymentIntent, options);
Parameters
Return value

None.

Examples
chargebee.load3DSHandler().then(threeDSHandler => {
  // Set the payment intent.
  threeDSHandler.setPaymentIntent(paymentIntent);
  // Additional logic here.
});
chargebee.load3DSHandler().then(threeDSHandler => {
   // In case you are using Adyen web components, you can pass the Adyen instance to this method.
  threeDSHandler.setPaymentIntent(paymentIntent, {
    adyen: adyenCheckoutInstance,
  });
});

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, then pass the updated payment intent to this method.

Syntax
threeDSHandler.updatePaymentIntent(paymentIntent);
Parameters
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();
}

getPaymentIntent()

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

Syntax
threeDSHandler.getPaymentIntent();
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. The payment intent ID can then be used to create subscriptions or create card payment sources for the customer.

Syntax
threeDSHandler.handleCardPayment(paymentInfo, callbacks);
Parameters
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(
    {
      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 of 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.
      },
    }
  ).then(authorizedPaymentIntent => {
    // Make an API call to your server to use the authorized payment intent
    // to create a subscription.
    return createSubscriptionApi(authorizedPaymentIntent.id);
  });
}

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

Bancontact payment handler

The Bancontact payment handler integrates the Bancontact payment method on your site or application.

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();
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);
Parameters
Return value

None.

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

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

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

The paymentInfo fields to pass depend on the gateway that processes the payment. Because Smart routing can select any of your configured gateways, pass the fields required by every gateway you have enabled for Bancontact. For Adyen, pass either element or card; the payment fails if you pass neither.

Return value

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

Example

Wallet-based payments

PayPal payment handler

The PayPal payment handler integrates the PayPal payment method on your site or application.

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

setPaymentIntent()

Sets the payment intent for payment processing.

Syntax
paypalHandler.setPaymentIntent(paymentIntent);
Parameters
Return value

None.

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

updatePaymentIntent()

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

Syntax
paypalHandler.updatePaymentIntent(paymentIntent);
Parameters
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);
  });
}

mountPaymentButton()

Mounts the PayPal payment button to the DOM.

Syntax
paypalHandler.mountPaymentButton(selector, options);
Parameters
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");
});

handlePayment()

Waits for payment processing to complete the transaction.

Syntax
paypalHandler.handlePayment(callbacks);
Parameters
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);
  });

Google Pay payment handler

The Google Pay payment handler integrates the Google Pay payment method on your site or application.

getPaymentIntent()

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

Syntax
googlePayHandler.getPaymentIntent();
Return value

Returns the payment intent object.

setPaymentIntent()

Sets the payment intent for payment processing.

Syntax
googlePayHandler.setPaymentIntent(paymentIntent);
Parameters
Return value

None.

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

updatePaymentIntent()

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

Syntax
googlePayHandler.updatePaymentIntent(paymentIntent);
Parameters
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);
  });
}

mountPaymentButton()

Mounts the Google Pay button to the DOM.

Syntax
googlePayHandler.mountPaymentButton(selector, buttonOptions, paymentOptions);
Parameters
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");
});

handlePayment()

Waits for payment authorization to complete.

Syntax
googlePayHandler.handlePayment(callbacks);
Parameters
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
  });

Apple Pay payment handler

The Apple Pay payment handler integrates the Apple Pay payment method on your site or application.

canMakePayments()

Checks whether the device supports the Apple Pay payment method.

Syntax
applePayHandler.canMakePayments();
Return value

Returns a boolean value indicating Apple Pay support.

Example
const isApplePayAvailable = applePayHandler.canMakePayments();

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(merchantIdentifier);
Parameters
Return value

Returns a promise that resolves to a PaymentCredentialStatusResponse object.

Example
applePayHandler.applePayCapabilities("YOUR_APPLE_PAY_MERCHANT_ID").then(capabilities => {
  switch (capabilities.paymentCredentialStatus) {
    case "paymentCredentialsAvailable":
      // Display an Apple Pay button and offer Apple Pay as the 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;
  }
});

mountPaymentButton()

Mounts the Apple Pay button to the DOM.

Note

Before calling this method, check whether the device supports Apple Pay using one of the following methods:

Syntax
applePayHandler.mountPaymentButton(selector, options);
Parameters
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"
  }
});

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

Payconiq by Bancontact handler

The Payconiq by Bancontact payment handler 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 by opening a modal popup overlay that displays a QR code for the customer to scan with their Payconiq app.

The modal stays open while the customer scans the QR code and completes the payment. It closes automatically when authorization completes.

Syntax
chargebee.handlePayment("payconiq_by_bancontact", options);
Parameters
Return value

Returns a promise that resolves to a payment intent object.

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 status is `in_progress` at this point - customer needs to scan QR code.
    // Poll for authorization before creating subscription.
    return waitForAuthorization(intent.id).then(authorizedIntent => {
      return createSubscription(authorizedIntent.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());
}

Venmo handler

The Venmo payment handler 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.

Syntax
venmoHandler.getPaymentIntent();
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();
}

setPaymentIntent()

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

Syntax
venmoHandler.setPaymentIntent(paymentIntent);
Parameters
Return value

None.

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

updatePaymentIntent()

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

Syntax
venmoHandler.updatePaymentIntent(paymentIntent);
Parameters
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);
  });
}

mountPaymentButton()

Mounts the Venmo payment button to the DOM.

Syntax
venmoHandler.mountPaymentButton(selector);
Parameters
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");
});

handlePayment()

Waits for payment processing to complete the transaction.

Syntax
venmoHandler.handlePayment(callbacks);
Parameters
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);
  });

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
  • 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);
Parameter
paymentMethodType
required, Enum
Name of the payment method type.
Allowed Values
ideal
sofort
bancontact
dotpay
netbanking_emandates
klarna_pay_now
direct_debit
paymentOptions
optional, Object
Options for the payment method type.
Return value

A promise that resolves to an authorized payment intent object.

iDEAL payment handler

The iDEAL payment handler integrates the iDEAL payment method on your site or application.

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.

Parameters

iDEAL uses the common bank handlePayment() parameters. See Initiating bank payments for the full paymentInfo reference, including userName and userEmail. These two fields are required for the Stripe gateway (userName must match the name on the payer's bank account exactly). Because Smart routing can select any of these gateways, provide both fields for every iDEAL payment.

Example
chargebee.handlePayment("ideal", {
  paymentIntent: () => {
    // Make a call to your server to create a Chargebee payment intent.
    return createPaymentIntent();
  },
  callbacks,
  paymentInfo: {
    // Required for Stripe.
    userName: "Jane Doe",
    userEmail: "janedoe@example.com",
  }
});

mountBankList() deprecated

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

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>
idealPaymentHandler.mountBankList(selector, options);
Parameters
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",
  });
});

getSelectedBank() deprecated

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

Syntax
idealHandler.getSelectedBank();
Return value

Returns an object containing the details of the selected bank:

{
  id: 'bank-id',
  name: 'Name of the bank.'
}

SOFORT payment handler

The SOFORT payment handler integrates the SOFORT payment method on your site or application.

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.

Parameters

SOFORT uses the common bank handlePayment() parameters. See Initiating bank payments for the full paymentInfo reference. country, userName, and userEmail are required for the Stripe gateway. Adyen, Mollie, and Checkout.com do not require paymentInfo fields. Because Smart routing can select any of your configured gateways, pass the Stripe fields whenever Stripe is enabled for SOFORT.

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

Klarna Pay Now payment handler

The Klarna Pay Now payment handler integrates the Klarna Pay Now payment method on your site or application.

The Klarna Pay Now payment handler object can be created by loading the payment method using 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("klarna_pay_now", paymentOptions);
Parameters

If you pass cardBillingAddress, include firstName and lastName. Chargebee.js rejects the payment if those names are missing.

Return value

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

Example
chargebee.load("klarna_pay_now").then(() => {
  chargebee.handlePayment("klarna_pay_now", {
    paymentIntent: () => {
      return createPaymentIntent();
    },
    paymentInfo: {
      userEmail: "jane.doe@example.com",
      country: "DE",
      lineItems: [
        {
          amount: 2500,
          description: "shoes",
          unitAmount: 2500,
          taxAmount: 0,
          id: "li_324r3r3rd32d",
          quantity: "1",
        },
      ],
    },
  });
});

DotPay payment handler

The DotPay payment handler integrates the Online Banking Poland (DotPay) payment method on your site or application.

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

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);
Parameters
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",
      },
    },
  },
});

getSelectedBank()

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

Syntax
dotpayHandler.getSelectedBank();
Return value

Returns an object containing the details of the selected bank:

{
  id: 'bank-id',
  name: 'Name of the bank'
}

Netbanking payment handler

The Netbanking payment handler integrates the Netbanking payment method on your site or application.

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);
Parameters
Return value

None.

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

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, then pass the updated payment intent to this method.

Syntax
netBankingHandler.updatePaymentIntent(paymentIntent);
Parameters
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);
  });
}

getPaymentIntent()

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

Syntax
netBankingHandler.getPaymentIntent();
Return value

Returns the payment intent object.

fetchBankList()

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

Syntax
netBankingHandler.fetchBankList(options);
Parameters
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.",
  },
]
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.
  });

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

UPI payment handler

The UPI payment handler integrates the UPI payment method on your site or application.

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);
Parameters
Return value

None.

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

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, then use this method to set the updated payment intent to the UPI payment handler.

Syntax
upiHandler.updatePaymentIntent(paymentIntent);
Parameters
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);
  });
}

getPaymentIntent()

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

Syntax
upiHandler.getPaymentIntent();
Return value

Returns the payment intent object.

fetchUpiInstalledAppList()

Applicable only for

Retrieves the list of supported UPI apps for the user's device. Use this list to display the list of supported UPI apps for the user to select from. Once the user selects a UPI app, call handlePayment() with the selected UPI app id passed as the paymentInfo.upi_app parameter.

Syntax
upiHandler.fetchUpiInstalledAppList();
Return value

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

[
  {
    name: 'Google Pay',
    id: 'gpay'
  },
  {
    name: 'PhonePe',
    id: 'phonepe'
  }
]
Example
chargebee.load('upi')
  .then((upiHandler) => {
    upiHandler.setPaymentIntent(intent);
    return upiHandler.fetchUpiInstalledAppList();
  })
  .then((upiAppList) => {
    // Display list of supported UPI Apps.
    // Call `upiHandler.handlePayment()` with the `paymentInfo.upi_app` parameter set to the selected `upiAppList[i].id`.
  });

handlePayment()

Initiates the UPI payment process. Once the payment is authorized, the promise resolves with the authorized payment intent. The payment intent ID can then be used to create subscriptions or payment methods.

Razorpay

For Razorpay gateway, the following flow is followed:

  • Desktop Web: The function opens a modal popup with a UPI QR code. The user can scan this QR code using the UPI app on their mobile device and complete the UPI mandate authorization.
  • Mobile Web: The function opens a modal popup where the user can select a UPI app. When the user selects a UPI app, Chargebee opens it for the user to complete the UPI mandate authorization. Optionally, if you want to implement the UPI app selection UI, see fetchUpiInstalledAppList().
dLocal

For dLocal gateway, the function redirects to the dLocal payment page where the user can complete the UPI mandate authorization.

Syntax
upiHandler.handlePayment(paymentInfo, callbacks);
Parameters
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.
  // For Razorpay gateway:
  const paymentInfo = {
    customer: {
      firstName: 'John',
      lastName: 'Kennedy',
      email: 'john@example.com',
      phone: '9999999999',
    },
    upi_app: 'gpay', // Only for Razorpay gateway and mobile web browsers (Android or iOS)
    additionalData: {
      planId: 'pro_plan',
      paymentType: 'recurring'
    }
  };

  return upiHandler
    .handlePayment(paymentInfo)
    .then((paymentIntent) => {
      // Payment intent is `authorized`.
      // Use the authorized payment intent to create a subscription.
      return createSubscriptionApi(paymentIntent.id);
    })
    .catch((error) => {
      console.error('Payment failed:', error);
    });
}

For dLocal gateway, the paymentInfo structure includes additional required fields such as document and shippingAddress. See the UPI tutorial for complete gateway-specific examples.

Direct Debit handler

The Direct Debit payment handler integrates the Direct Debit payment method on your site or application.

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);
Parameters
Return value

None.

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

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, then pass the updated payment intent to this method.

Syntax
directDebitHandler.updatePaymentIntent(paymentIntent);
Parameters
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);
  });
}

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.

Parameters

Direct Debit uses the common bank handlePayment() paymentInfo fields. See Initiating bank payments. Requirements vary by scheme and gateway (customer, bankAccount, useGateway, plaid, and mandateText). Pass customer.billingAddress (not a top-level customerBillingAddress field).

For SEPA via GoCardless, if you collect bank details yourself instead of setting useGateway, the required bankAccount fields depend on countryCode:

countryCode

Country

Required bankAccount fields

AT, FI, AX, DE, LV, LT, LU, NL, SK, SI

Austria, Finland, Åland Islands, Germany, Latvia, Lithuania, Luxembourg, Netherlands, Slovakia, Slovenia

accountNumber, bankCode, countryCode

BE, EE

Belgium, Estonia

accountNumber, countryCode

CY, FR, GF, GP, YT, RE, BL, MF, PM, GR, IT, MC, PT, SM, ES

Cyprus, France, French Guiana, Guadeloupe, Mayotte, Réunion, Saint Barthélemy, Saint Martin, Saint Pierre and Miquelon, Greece, Italy, Monaco, Portugal, San Marino, Spain

accountNumber, routingNumber, bankCode, countryCode

IE, MT

Ireland, Malta

accountNumber, routingNumber, countryCode

Alternatively, pass iban instead of those local bank fields.

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

Voucher-based payments

Boleto handler

The Boleto payment handler integrates the Boleto payment method on your site or application.

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);
Parameters
Return value

None.

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

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, then pass the updated payment intent to this method.

Syntax
boletoHandler.updatePaymentIntent(paymentIntent);
Parameters
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);
  });
}

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

When the payment intent has no reference_id, Stripe requires customer (firstName, lastName, email), billingAddress, and taxId.

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

Cryptocurrency payments

Stablecoin handler

The Stablecoin payment handler integrates the Stablecoin payment method on your site or application.

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

handlePayment()

Initiates the payment process.

The function opens a pop-up where users complete the payment. After successful authorization, the payment intent status changes to authorized, the pop-up closes automatically, and the promise resolves.

The payment intent ID can then be used to create subscriptions or payment methods.

Syntax
chargebee.handlePayment("stablecoin", options);
Parameters
Return value

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

Example
chargebee.load("stablecoin").then(() => {
	chargebee.handlePayment("stablecoin", {
		paymentIntent: () => {
			return createPaymentIntent();
		}
	}).then(intent => {
		// Payment intent is `authorized`.
		return createSubscription(intent.id);
	}).catch(err => {
		console.error('Payment failed:', err);
	});
});