UPI Intent for EBANX payment gateway integration
UPI Intent enables customers in India to pay by selecting a UPI app on the Payment Page and approving the payment in that app through the EBANX integration.
Unified Payments Interface (UPI) is an Indian instant payment system developed by the National Payments Corporation of India (NPCI). UPI enables users to link multiple bank accounts to a single mobile application and complete bank-to-bank transactions from a mobile device.
Zuora supports UPI transactions in INR through the EBANX payment gateway integration. To support UPI one-time and recurring payment flows, implement a hosted payment page through Payment Pages 2.0.
Zuora recommends UPI as a payment method when customers complete payments in a mobile browser. UPI Intent flows are designed for mobile payment experiences and are not supported on desktop browsers.
Zuora uses EBANX Real-Time Reconciliation (RTR) to process UPI payments. You must configure RTR for UPI payments.
Supported and unsupported features
The following table lists the supported and unsupported operations and features for UPI on the EBANX payment gateway integration.
| Supported | Unsupported |
|---|---|
| One-time payment processing with UPI QR code | Payment cancel (void) |
| Recurring payment processing with UPI Collect and UPI Autopay | Non-referenced refund |
| Payment method creation with initial payment | Batch gateway reconciliation |
| Payment method creation without a one-time payment | Delayed capture |
| Referenced refund | Stored Credential Transactions framework and Network Transaction Identifier (NTI) sharing |
| Real-Time Reconciliation | Creation of UPI payment methods through the UI or API |
| Mandate-based recurring debit flow | Asynchronous payment statuses |
One-time payment flow
Zuora supports one-time UPI payments through a UPI QR code flow. When the hosted payment page is initiated, a QR code is displayed for the customer to scan with a UPI application and complete the payment.
After the customer authorizes the payment, a success page is displayed. This flow supports one-time payments only, and no payment token is created for future use.
Payment method creation
On the hosted payment page, the customer enters a Virtual Payment Address (VPA) and submits the payment. Zuora then calls the EBANX Direct API with payment_type_code set to upi-intent, along with the required customer and charge parameters.
If EBANX returns a successful synchronous response, Zuora creates a payment with the payment status set to Processed and the gateway state set to Submitted. Zuora then listens for EBANX webhook and RTR events that provide the final payment status. The possible statuses are APPROVED, DECLINED, EXPIRED, and FAILED.
Zuora updates the gateway state based on the EBANX UPI payment status:
- If the status is
APPROVED, the gateway state is set toSettled. - If the status is
DECLINED,FAILED, orEXPIRED, the gateway state is set toFailedToSettle.
If Zuora does not receive an EBANX webhook event before the timer expires, Zuora returns an error callback with the Payment_Status_Unknown error code. In this case, use the Retrieve a payment API operation to query the final payment status.
If EBANX immediately rejects the request, the returned error message is displayed on the hosted payment page. No payment is recorded and no UPI payment method is created.
Stored token information
After a payment method is created successfully, you can retrieve the UPI payment method through the Zuora UI and REST API.
In the Electronic Payment Methods section of the customer account page, Zuora stores EBANX-issued tokens and mandate-related identifiers in the token fields. Zuora uses these values for subsequent recurring UPI Autopay payments and for mandate management.
Recurring payment flow with UPI Autopay
UPI Autopay on EBANX is a mandate-based recurring payment framework. The customer approves an enrollment one time in a UPI application, and Zuora and EBANX reference this enrollment for subsequent merchant-initiated transactions.
To comply with the Reserve Bank of India (RBI) and NPCI regulations, Zuora sends a pre-debit notification (PDN) to UPI users before each recurring debit. Zuora sends the PDN through the EBANX enrollment notification endpoint. A PDN is required before a recurring charge can be initiated.
Zuora handles the PDN automatically for recurring UPI payments. For each eligible recurring debit, Zuora sends the PDN 24 to 48 hours before the scheduled payment date.
Because a PDN must be sent before the recurring debit, only scheduled recurring charges are supported for this flow.
Recommended invoice timing and payment terms
When you use UPI Autopay for recurring collections, Zuora recommends that you set the payment terms to Net 3.
Net 3 provides enough lead time for Zuora to send the PDN before the recurring debit is due and reduces the risk of collection timing conflicts.
Conditions for triggering pre-debit notifications
When an invoice is posted, Zuora sends a PDN request to EBANX only if all of the following conditions are met:
- The invoice has an outstanding balance.
- The payment method type is UPI.
- The payment gateway is an EBANX gateway that is configured for UPI Autopay.
- The transaction currency is INR.
- The invoice is not already associated with an active PDN for the current balance.
Retry behavior
If a PDN request fails, Zuora logs the failure and does not attempt the recurring debit until a successful notification is acknowledged. Zuora retries the notification according to the configured retry schedule until EBANX confirms delivery or the retry window expires.
If the recurring payment itself fails after a successful PDN, Zuora does not automatically retry the payment. To attempt collection again after a failed recurring payment, send a new PDN through the PDN API and then create the payment manually.