Frontend Capabilities

# Integrate UPI

UPI (Unified Payments Interface) is a payment method that allows customers to complete online payments using their bank credentials. It is one of the preferred online payment methods in India.

This tutorial shows you how to integrate Chargebee.js with UPI (mandates) on your website and create a subscription after checkout.

# Supported gateways

UPI mandates are supported by the following gateways in Chargebee:

# Prerequisites

Before you begin, follow these steps:

  1. Configure the gateway settings:
  1. Ensure that Smart routing (opens new window) is configured to select the appropriate gateway for UPI payments.

# Set up Chargebee.js

# Include the Chargebee.js script

To use Chargebee.js, you must include the script in your HTML page. You only need to do this once per page.

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

# Initialize a Chargebee instance

After including the script, initialize Chargebee.js in your JavaScript code. The initialization creates a Chargebee instance object that you can use to access Chargebee.js features.

Initialize Chargebee.js after the page has loaded and provide your site configuration. This object is used to create components.

# Example

const chargebee = Chargebee.init({
  site: "YOUR_CHARGEBEE_BILLING_SUBDOMAIN", // Your test site.
  domain: "https://mybilling.acme.com", // Optional: custom domain.
  publishableKey: "test__" 
});
1
2
3
4
5

WARNING

If you want to reinitialize Chargebee.js within the same session, call tearDown() to clean up before calling init() again.

# Create a payment intent

Create the payment intent on your server using the Create a payment intent API, then return it to the client. The payment method handler uses the payment intent internally to perform authorization.

About `payment_intent`

A payment_intent (opens new window) resource manages a customer's payment session. It tracks the amount, currency, payment status, and failed payment attempts, and helps prevent duplicate charges for the same session. The payment_intent automatically updates its status based on authorization and capture events, and issues refunds if an error occurs after payment.

# Call your backend to fetch the payment intent frontend

WARNING

Always create the payment intent from your backend to avoid exposing sensitive data.

function createPaymentIntent() {
  return fetch('/payment-intents', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 500,
      currency_code: 'INR',
      payment_method_type: 'upi'
    })
  }).then(function(response) {
    return response.json();
  }).then(function(responseJson) {
    return responseJson.payment_intent;
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Call Chargebee API to create a payment intent backend

Create a payment intent using the Create Payment Intent API (opens new window):

curl https://{site}.chargebee.com/api/v2/payment_intents \
  -u {fullaccess_api_key}: \
  -d amount=500 \
  -d currency_code=INR \
  -d payment_method_type=upi
1
2
3
4
5

# Load the UPI payment method and start the payment flow

# Load UPI payment method frontend

Load the UPI integration using the load() method:

chargebee.load('upi');
1

# Set payment intent frontend

After loading the UPI handler, set the payment intent using setPaymentIntent():

chargebee.load('upi').then((upiHandler) => {
  upiHandler.setPaymentIntent(intent);
});
1
2
3

# (Optional) Fetch and display the list of UPI Apps

Applicable only for

Optionally, retrieve the list of supported UPI apps for user's device using fetchUpiInstalledAppList(), render it, and let the user select the UPI app.

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`.
});
1
2
3
4
5
6
7
8
9

# Handle payment frontend

Call handlePayment() with the paymentInfo argument containing customer details and gateway-specific information.

# Razorpay

For Razorpay, you can either let Chargebee handle the UPI flow or, optionally, let the user select the UPI app. The latter is applicable only for mobile web browsers (Android or iOS).

# Option 1: Let Chargebee handle the UPI flow

This is the simplest way that works for both desktop web and mobile web browsers.

DETAILS
  • Promises
  • Callbacks
# Option 2: Let the user select the UPI app

Note

Applicable only for mobile web browsers (Android or iOS).

For mobile web browsers (Android or iOS), you can let the user select the UPI app from the list of supported UPI apps.

DETAILS
  • Promises
  • Callbacks

# dLocal

For dLocal, Chargebee handles the UPI flow on calling handlePayment() with the appropriate arguments.

DETAILS
  • Promises
  • Callbacks

TIP

For complete parameter documentation, see the API Reference.

On successful authorization, the status of payment_intent changes to authorized, and Chargebee redirects the user back to your website (payment authorization page).

# Create a subscription

# Call your backend to create a subscription frontend

After the payment intent is authorized, call your backend to create a subscription using the payment intent ID and subscription details:

function createSubscription(paymentIntentId) {
  return fetch('/subscriptions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      paymentIntentId,
      plan_id: 'pro_plan',
      plan_quantity: 1,
      billingAddress: {
        // Add billing address details.
      },
      customer: {
        // Add customer details if the subscription is to be created for an existing customer.
      }
    })
  }).then(response => response.json());
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Use webhooks for production

Use webhooks (opens new window) for production use, instead of making the subscription creation request from the frontend, it's more secure and reliable to respond to webhooks from Chargebee on the backend. Listen to the payment_intent_updated (opens new window) event via webhooks and create the subscription when the payment_intent.status (opens new window) is authorized.

# Create a subscription backend

Pass the ID of the successfully authorized payment_intent to Chargebee's Create a subscription API (opens new window).

curl  https://{site}.chargebee.com/api/v2/customers/__test__8asz8Ru9WhHOJO/subscription_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d payment_intent[id]="{payment_intent_id}"
     -d subscription_items[item_price_id][0]="pro_plan" \
     -d subscription_items[quantity][0]=1
1
2
3
4
5
6

← Integrate Dotpay →