Overview

Required plan

This feature or setting is available to all customers on any Recurly subscription plan.

Supported gateways

Recurly currently supports UPI AutoPay transactions through Ebanx gateway.

Definition

Integrating Recurly with Ebanx enables merchants to leverage UPI payment methods, including UPI AutoPay. This powerful combination aligns Recurly's subscription management with Ebanx’s gateway capabilities for seamless payments in India.

Key details

What is UPI

UPI (Unified Payments Interface) is a real-time payment system in India that consolidates multiple bank accounts into a single mobile app. Users can pay using a VPA (Virtual Payment Address)—for example, payer@bankname—which masks their bank details for increased security.

What is UPI AutoPay?

UPI AutoPay facilitates compliant recurring payments from an Indian bank account. Consumers can schedule recurring payments for subscriptions, bills, and more through their UPI app. UPI is set up initially with an enrollment into a mandate. Consumers need to authorize this enrollment, and subscriptions cannot be activated without this step.

What is a VPA?

A Virtual Payment Address (VPA), such as payer@bankname, uniquely identifies a consumer’s bank account in a UPI app. It conceals direct bank information; therefore, Recurly does not see the underlying payment method.

UPI AutoPay Limitations

UPI AutoPay is specifically designed for subscriptions, and subscriptions only. It is not flexible like a credit card and does not support many of the functions available in Recurly where credit cards and some other payment methods are available. Some notable limitations include:

• One-time transactions, including force collections and purchases, are not supported.
• Subscription item / add-ons are not supported at this time due to subscription-specific mandate creation requirements with UPI.
• Adding a subscription through the UI: Since UPI requires a customer in session to confirm the subscription, this is not recommended.
• Changing billing information: Recurly will store the consumer's VPA for future subscriptions, but the billing information is stored within the UPI App itself, not with the gateway or Recurly.
• Changing the renewal date defined by the mandate: If a customer wants to change their renewal date, they need to resubscribe and confirm a new mandate. UPI mandates are strict about the date we can charge the consumer, and so modifications of the date after enrollment are not recommended as declines will occur. This includes using Calendar billing / aggregation features.

What can users do within the UPI App?

Consumers will be required to confirm their signup enrollment via the UPI app whenever they are subscribing to a plan. As a result, all UPI transactions begin life as a scheduled transaction. If the consumer does not confirm the subscription enrollment, the scheduled transaction will fail and the subscription will be expired.

Consumers can pause or cancel subscriptions directly from their UPI app and must confirm transactions of 15000 INR or higher within one hour of receiving a push notification.

They also receive a pre-renewal push notification 24–48 hours prior to their next billing date, giving them another opportunity to pause or cancel the subscription prior to charging. This push notification occurs for every charge for the lifetime of their subscription.

Recommended integration

Currently, UPI AutoCollect is not supported on Recurly Checkout or Hosted Payment Pages.

Use cases

• Subscription Plans: Simplify UPI AutoPay transactions by merging the Recurly subscription platform with Ebanx.
• Trial Subscriptions: Allow your customer to authorize their enrollment and enjoy a free trial before their first charge.

Required Fields

UPI AutoPay together require a minimum of fields to create a mandate for a recurring subscription. The minimum required fields to submit a UPI AutoPay transaction are as follows:

• VPA
• Email Address
• Customer First and Last Name
• Customer Billing Address (Street Address, City, Region/State, Country, Postal Code / PIN Code)
  • Regional Mapping:
    • Street Address is the House/Street Name and Number (EX: HOUSE NO. 32, MG ROAD)
    • City is the Locality and City in India (Ex: VILLAGE OF AMARPUR, NEW DELHI)
    • State is the State or Union Territory in India (ex: MAHARASHTRA)
    • Postal Code is the PIN Code (ex: 110019)
    • Country is the Country (ex: IN)
• Phone Number

Creating Subscriptions

Use the subscription or purchase endpoints to create subscriptions with UPI AutoPay. Provide the VPA in Recurly’s payment_gateway_references object and specify upi_vpa as the reference type. See Recurly documentation for more details.

Billing information updates

UPI AutoPay doesn’t support direct updates to a VPA. Customers must update their banking information in the UPI app directly.

If a customer’s VPA changes, cancel the existing subscription and have them re-enroll with the new VPA to create a new mandate.

Enrollments and Charges

When creating a subscription, ensure you are listening to the following webhooks. UPI AutoPay is an asynchronous payment method as transactions initially begin in a scheduled state until the consumer authenticates in-app.

Signup transactions will begin in a scheduled state before moving to failed or approved.

Listen for the following webhooks:

• payment.scheduled
• subscription.created

Once the consumer authenticates in-app (UPI App), listen for the following webhooks:

• payment.transaction_status_updated
• payment.success
• charge_invoice.paid

You can Fetch a transaction, invoice, or subscription status to update your records. When the invoice moves into a paid state, this indicates a successful consumer authentication from the UPI Application.

Unconfirmed or Rejected Enrollments

If, when signing up, the consumer rejects the enrollment or fails to respond to the in-app push notification, the subscription will move into an expired state, and the invoice/transaction will fail. Listen for the following events.

• subscription.expired
• charge_invoice.failed

These indicate the enrollment or charge was rejected upon signup.

Cancellations

If a customer cancels via the UPI app, Recurly webhooks will notify you. Subscriptions are automatically canceled in Recurly. Listen for the following webhook:

• subscription.canceled

Paused subscriptions

If a customer pauses via the UPI app, Recurly webhooks notify you. Subscriptions are automatically paused in Recurly. Listen for the following webhook:

• subscription.paused

Resumed Subscriptions

A customer may resume a paused subscription directly in the UPI app. Recurly sends a webhook, and the subscription is automatically resumed. If you prefer not to allow customers to resume after pausing, you can cancel the subscription in Recurly when you receive the pause webhook. Listen for the following webhook:

• subscription.resumed

Gateway tokens

UPI requires Recurly's gateway token approach, as each consumer’s VPA functions like a virtual account identifier (payer@bankname). Your integration must pass the VPA through payment_gateway_references object and ensure you are setting the reference type as upi_vpa and gateway_code parameters. Refer to Recurly’s API documentation for details.

Net terms and subscription updates

• Use Net Terms = 0 to avoid failed payments due to limited UPI charge windows.
• Avoid changing subscription prices for a fixed-price UPI mandate. If the price changes, the subscription must be canceled and re-created with new customer consent.

Testing

Refer to the Ebanx gateway documentation for testing procedures.

Retries

UPI AutoPay payments retries will not be allowed through typical retry logic (Basic or Intelligent Retries) as declined UPI transactions must be retried the same day. Retries are not yet supported, but are planned.

Checkout flow

During the checkout, allow your consumer to provide their VPA (Virtual Payment Address) and pass it to Recurly using documented gateway token parameters. This will create an enrollment request to the gateway, and if accepted by the customer within their UPI app, will set up a subscription and, if the plan is not set up for a trial, charge the first amount according to the plan currency/amount settings. Ensure you have INR currency and applicable pricing set up properly.

Renewals will occur according to plan settings, unless the customer interrupts the subscription from the UPI Application on their phone. We recommend enabling specific webhooks so that you can act on these cases to pause, resume, or cancel the subscription based on the customer’s request.

Recommended Webhooks

Since UPI - Recurring customer actions are outside of Recurly's view, our Ebanx integration supports notifying Recurly when a customer has cancelled or paused their UPI mandate. It is recommended to listen for certain Recurly webhooks if you have selected 'Manual' in your Mandate Preferences settings.

• Cancelled Subscription: Will be sent if the customer cancels their UPI mandate externally.
• Paused Subscription Will be sent if the customer pauses their UPI mandate externally.
• Resumed Subscription Will be sent if the customer unpauses their UPI mandate externally.

Other good webhooks to listen for are:

• charge_invoice.created: Will be sent when a customer initially signs up for a subscription with no trial.
• charge_invoice.processing: Will be sent when a customer signs up for a subscription with no trial, and the enrollment has not been confirmed.
• charge_invoice.paid: Will be sent when a customer signs up for a subscription with no trial, and the enrollment has been confirmed.
• charge_invoice.failed: Will be sent when a customer signs up for a subscription with no trial, and the enrollment has been rejected by the customer.
• payment.transaction_status_updated: Will be sent when a customer signs up for a subscription with no trial, and the enrollment has been confirmed.
• payment.scheduled: Will be sent when a customer signs up for a subscription with no trial, and the enrollment has not been confirmed.
• subscription.created: Will be sent when a customer signs up for a subscription with or without a trial.
• subscription.expired: Will be sent when a customer signs up for a subscription with or without a trial and does not confirm the enrollment.

Note: Subscriptions with a plan inclusive of a trial are not initially invoices. You will only receive subscription and payment webhooks, and not invoice webhooks. Look for payment.scheduled and updates accordingly when using Trials.

FAQs

Q: Do you support UPI QR Code or One-Time transactions?

• No. Our integration with Ebanx only supports recurring transactions.

Q: My UPI Subscription is failing, how can I fix this?

• Ensure the subscription price has not changed without customer-engagement to re-subscribe.
• Ensure your Mandate Management settings are set properly. If they are set to manual, you may have missed a webhook that requires a change to the subscription status.
• Ensure your customer is responding to the UPI application push notifications when pre-renewal notifications are sent or on charges that are above 100000 INR.
• Ensure you have not ignored a webhook to pause or cancel a subscription. Your customer may have requested such, and you will need to act on the specific subscription via API or within the UI.

Q: I updated my customer's VPA on an existing subscription, but the original bank account was charged. How do I fix this?

• Billing Info Updates are not supported when using UPI AutoPay. Cancel the current subscription and have your customer resubscribe with their new VPA.