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

# Handle payment frontend

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

The function opens a modal popup where the user can complete the UPI mandate authorization. The user remains on your website while the modal is open. Once the payment is authorized, the modal closes automatically and the promise resolves with the authorized payment intent.

TIP

Show a loader animation while calling handlePayment() for the duration of the payment authorization process. This helps to give feedback to the user, especially while they are waiting for the modal to open.

  • Promises
  • Callbacks

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

TIP

For complete parameter documentation, see the API Reference.

# 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: 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 →