UPI via Stripe
This feature is a Private Beta release. Contact Chargebee Support to enable UPI via Stripe for your live and test sites.
Chargebee supports Unified Payments Interface (UPI) through the Stripe payment gateway, letting you offer Indian customers a familiar, bank-native payment experience at checkout.
UPI is a real-time payment system governed by the National Payments Corporation of India (NPCI). When a customer selects UPI during checkout:
- On desktop, a QR code is displayed for the customer to scan using any UPI-enabled app (such as Google Pay, PhonePe, or Paytm).
- On mobile, Stripe automatically hands off to an installed UPI app so the customer can authorize without scanning a QR code.
- The customer authorizes the payment and mandate directly in their UPI app—no redirect to an external payment page.
- On successful authorization, Chargebee sets up a recurring mandate so future subscription renewal charges can be collected automatically in the background.
For more information on how Stripe handles UPI, see Stripe's UPI documentation.
Key features
- Supports subscription payments and one-time charges.
- Supports INR (Indian Rupee) as the payment currency.
- Saves the payment method as a mandate for automatic future collections (MIT).
- Compatible with:
Prerequisites
Before you set up UPI in Chargebee:
- Stripe is configured as a payment gateway in Chargebee.
- UPI is enabled in your Stripe account. Contact Stripe to activate UPI for your live account.
- Your Chargebee site is configured to collect payments in INR.
Configure UPI via Stripe in Chargebee
To enable UPI payments through Stripe in Chargebee:
- Log in to your Chargebee Billing site.
- Go to Settings > Configure Chargebee > Payment Gateway.
- Select Stripe from the list of configured gateways.
- On the Configure Stripe page, turn on Unified Payments Interface (UPI).
- Click Apply to save your changes.
Configure Smart Routing
To ensure INR payments route to the correct Stripe gateway for UPI:
- Go to Settings > Configure Chargebee > Payment Gateways.
- Select Smart Routing.
- Under the For UPI section, set the rule to route INR payments to your Stripe gateway.
Configuring webhooks
To keep your Chargebee–Stripe integration in sync, configure webhooks in Stripe. Webhooks let Chargebee receive real-time updates from Stripe when important events occur.
For this integration to work correctly, enable the following events:
This event notifies Chargebee when a refund is updated in Stripe, so refund status is reflected accurately in your Chargebee account.
Checkout flow
Your customer completes the following steps at checkout when subscribing with UPI via Stripe:
- The customer reviews the order details on the Your order page and clicks Proceed To Checkout.
- The customer enters their email address and clicks Next.
- The customer enters their account details—name and phone number—and clicks Next.
- The customer enters their billing address and clicks Next.
- The customer selects UPI on the Add your payment details page, enters the required payment details, and clicks Next.
- The customer reviews the full order summary on the Complete your order page—including account details, billing address, and UPI payment details—and clicks Pay & Subscribe.
- The customer authorizes the payment and mandate in their UPI app. On desktop, a QR code is displayed to scan. On mobile, Stripe automatically hands off to an installed UPI app.
- After the customer scans and approves, the subscription is created. The payment and mandate setup complete automatically and the page shows a Close button.
Note
The screenshots above show the UPI checkout flow in Stripe's test environment. In production, customers scan the QR code in their real UPI app.
Recurring payments and mandate behavior
When a customer completes UPI checkout in Chargebee, a UPI mandate is automatically set up. This mandate authorizes Chargebee to collect future subscription renewal charges without requiring the customer to scan a QR code each time.
Mandate details
| Mandate property | Value |
|---|---|
| Amount type | Maximum (covers any charge up to the mandate cap) |
| Mandate cap | ₹15,000 |
| Billing interval | Derived from the subscription plan frequency |
Customer-initiated transactions (CIT)
For any customer-present charge—including first-time checkout, a new purchase with a saved UPI payment method, or adding UPI from the self-serve portal—the customer must authorize the payment in their UPI app. On desktop, they scan a QR code; on mobile, Stripe hands off to an installed UPI app. This is required by Stripe for all CIT UPI flows and cannot be bypassed.
Merchant-initiated transactions (MIT)
Once the mandate is set up, Chargebee collects subscription renewals automatically as off-session merchant-initiated transactions (MIT). No customer action is required.
Payment features
The following features are supported for UPI via Stripe.
| Feature | Description | Supported | Default state | Configuration or behavior |
|---|---|---|---|---|
| Integration sync mode | Defines how payment requests are processed and statuses are communicated between Chargebee and Stripe. | Yes (synchronous) | Synchronous | Chargebee waits for the customer to authorize the payment in their UPI app in-session (QR code on desktop, app handoff on mobile). The subscription is created only after the customer completes authorization. |
| Capture settings | Payment processing involves two stages: authorization and capture. Capture settings determine when funds are collected after authorization. | Yes | Auto capture | Auto capture is the default and only supported capture setting for UPI via Stripe. Funds are collected immediately after the customer approves the QR code. |
| Recurring billing (MIT) | Automatic off-session collection for subscription renewals using a saved mandate. | Yes | Enabled after initial CIT mandate setup | Chargebee collects renewals automatically using the UPI mandate set up during checkout. |
| Statement descriptor | Displays the business name on the customer's bank statement, helping them recognize charges and reducing disputes. | Yes | Disabled | Configure this under Settings > Configure Chargebee > Transaction Descriptor. |
| Refunds | Reversal of a collected payment back to the customer. | Yes | Available | Full and partial refunds are supported. Configure Stripe webhooks with the charge.refund.updated event to ensure refund status is reflected accurately in Chargebee. |
| Chargeback management | Handles chargeback events and applies configured actions on invoices and subscriptions. | No | Not applicable | UPI dispute handling is not supported in Chargebee. If a customer raises a dispute, issue a refund manually through your Stripe dashboard. |
| Fraud management | Uses gateway fraud signals to identify and flag high-risk transactions. | No | Not applicable | No UPI-specific fraud configuration is available in Chargebee. |
| Error intelligence | Provides standardized categorization of payment failures. | Yes | Enabled | Available through Stripe payment responses. No configuration is required. |
| Gateway transaction details | Provides access to raw gateway responses for transactions. | Yes | Enabled | Available on the transaction page under Error details. No configuration is required. |
| Adding payment methods in the Chargebee dashboard | Allows a payment method to be added in Chargebee when details are collected outside checkout. | No | Not applicable | UPI payment methods cannot be added from the Chargebee dashboard. Customers must complete the UPI checkout or portal flow to set up a mandate. |
Supported token formats
This section is relevant if you're building a custom checkout or migrating payment methods from another provider to Stripe.
| Token type | Description | Supported | Token field | Token format |
|---|---|---|---|---|
| Chargebee Payment Intent | Recommended token format when building a custom checkout using Chargebee.js. | Yes | payment_intent[id] | payment_intent_id |
| Chargebee token | Legacy token format supported for selected payment methods and gateways with Chargebee.js. Not recommended for new implementations. | No | token_id | Not applicable |
| Gateway permanent token | Permanent reference provided by the gateway for saved payment methods. | Yes | payment_method[reference_id] | Stripe Payment Method ID (pm_...) |
| Gateway temporary token | Short-lived token format that can be converted to a permanent token. | No | Not applicable | Not applicable |
Testing
Sandbox testing
Refer to Stripe's UPI documentation for instructions on testing UPI in the Stripe test environment. In test mode, QR code scanning is simulated automatically without requiring a real UPI app.
Production testing
Before you go live:
- Make sure UPI is enabled in your Stripe live account.
- Verify Smart Routing routes INR payments to your Stripe gateway under the For UPI section.
- Verify that webhook configuration is complete with the
charge.refund.updatedevent. - Run end-to-end testing using a real UPI-enabled bank account and a mobile device with a UPI app installed.
- Test both new checkout (CIT with QR flow) and a renewal scenario (MIT off-session) to confirm mandate collection works correctly.
Reconciliation
For financial reconciliation between Chargebee and Stripe, use the Chargebee transaction field id_at_gateway, which maps to the Stripe PaymentIntent ID. Retrieve that value from the Chargebee transaction details, then locate the matching transaction in your Stripe Dashboard or reports.
Limitations and important points
- Currency: UPI via Stripe supports INR only.
- Geography: UPI is available for customers with Indian bank accounts that have UPI enabled, and a UPI-supported bank app (such as Google Pay, PhonePe, or Paytm).
- QR code expiry: The QR code expires after approximately 5 minutes. If it is not scanned in time, the customer must restart checkout.
- No UPI ID entry: Chargebee's UPI integration uses Stripe's QR code flow. Customers do not enter their UPI Virtual Payment Address (VPA/UPI ID) during checkout.
- Portal add payment method: When a customer adds a UPI payment method from the self-serve portal and has a small pending invoice (below ₹1), the portal may fail to collect the pending balance during payment-method setup. Enable asynchronous payment collection in your Stripe gateway settings in Chargebee so invoice collection happens in the background and does not block adding the payment method.
Was this article helpful?