Creating an UPI Autopay Enrollment

UPI Autopay works by establishing an authorization, achieved through an enrollment process, between a merchant and a customer, and referencing it in every recurring payment.

By following this basic integration guide, you will understand how you can create enrollments and accept UPI Autopay recurring payments in your checkout, by using EBANX Direct API. To complete a payment with UPI Autopay you will need a few API calls that will create an enrollment for your customer, the recurring payment and provide the necessary information for the customer to complete the transaction.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.

Instructions

To complete a UPI Autopay enrollment, please follow the steps below.

1. Call the /ws/userenrollment API to create the Enrollment

   

   To start the recurring payment process, enroll the subscription using the /ws/userenrollment endpoint. This step involves collecting essential customer details and subscription parameters to establish the recurring billing agreement.

   Users will be required to complete a 2FA in order to accept this enrollment on their app. Once the process is complete, the customer will be enrolled for the recurring payment cycle.

   To trigger this process, you just need to call the endpoint /ws/userenrollment (server-side) with the following parameters:

   
   

   Basic parameters

   Parameter	Requirement	Description
   integration_key	Required	Your integration key
   payment_type_code	Required	Must be upi-collect-autopay
   operation	Required	Must be enrollment

   Enrollment data

   Parameter	Requirement	Description
   enrollment.merchant_enrollment_code	Required	Unique identifier associated with the enrollment.
   enrollment.country	Required	Two-letter country code. Set to "in" for India.
   enrollment.back_urls.success	Required	Callback URL for a successful response.
   enrollment.back_urls.failure	Required	Callback URL for a failure response.
   subscription.subscription_name	Required	Descriptor of the service being provided, which will be displayed in the customer's app. No special characters or alphanumeric allowed. (Currently only Gpay displays this information)
   subscription.expiration_date	Required	Defines when the enrollment is no longer valid and no further payments will be charged.
   subscription.frequency	Required	The billing cycle of the enrollment. Available frequencies are: weekly, biweekly, monthly, and ondemand.
   subscription.recurrence_value	Optional (only required if frequency is set to weekly, biweekly, or monthly)	If weekly, 1 to 7. If biweekly, 1 to 16. If monthly, 1 to 31.
   subscription.min_amount	Required	Minimum amount (per payment) during the validity of the subscription plan (in INR currency).
   subscription.max_amount	Required	Maximum amount (per payment) during the validity of the subscription plan (in INR currency).
   upi.vpa	Required	Subscription payer UPI ID. The standard format is 'payer@vpa'. (VPA is referred to as the customer's Virtual Payment Address linked with their bank account).

   
   
   note

   • When setting the max & min amount, any charge made outside the set value will require a new enrollment set-up with new values in the fields min_amount and max_amount.
   • The following parameters will be displayed in the user's UPI app with the subscription authentication request: subscription_name, expiration_date, frequency, min_amount, max_amount.
   • The predefined values for frequency set the rules for payment execution, but they don't automate the required actions.
     • Pre-debit notifications and payment requests must be managed manually.
     • Payments outside these rules will be declined.
     • If the time window is missed, the subscription status remains unchanged, and payments can proceed in the next window, the merchant can send a one-time request charge to cover such cases.
     • For more flexibility, consider using the "ondemand" as frequency.

   Sample request

   curl -X POST 'https://sandbox.ebanx.com/ws/userenrollment' \
   --header 'Content-Type: application/json' \
   --data '{
       {
       "integration_key": "{{integration_key}}",
       "payment_type_code": "upi-collect-autopay",
       "operation": "enrollment",
       "enrollment": {
           "country": "IN",
           "email": "{{customer_email}}",
           "merchant_enrollment_code": "{{unique_enrollment_code}}",
           "back_urls": {
               "success": "{{success_url}}",
               "failure": "{{failure_url}}"
           },
           "subscription": {
               "subscription_name": "Descriptor of the subscription.", 
               "expiration_date": "2025-12-30", 
               "frequency": "ondemand", 
               "min_amount": "1",
               "max_amount": "20000"
           },
           "upi": {
               "vpa": "payer@vpa"
           }
       }'

   A successful request will return a JSON response like the one below:

   {
     "status": "SUCCESS",
     "enrollment": {
       "merchant_enrollment_code": "{{unique_enrollment_code}}",
       "email": "email@example.com",
       "country": "IN",
       "back_urls": {
         "success": "{{success_url}}",
         "failure": "{{failure_url}}"
       },
       "subscription": {
         "subscription_name": "Descriptor of the subscription.",
         "expiration_date": "2025-12-30",
         "frequency": "ondemand",
         "min_amount": "1",
         "max_amount": "20000"
         },
         "upi": {
             "vpa": "payer@vpa"
         }
     }
   }

   note

   • For subscriptions with payment amounts under 15,000 INR, auto-debit is enabled: This means that for following transactions under 15,000 INR, PIN authentication for UPI transactions will not be required.
   • The merchant is required to make a charge request within 5 minutes of the enrollment acceptance in order to avoid another 2FA during the 2nd debit request (request for this remains the same as of the recurring payment mentioned in the next section). No PDN would be required for this charge.
   • Even with auto-debit enabled, subsequent payments will still require the mandatory pre-debit notification to the user.
   • Payments > 15,000 INR will always require user authentication.
     • Users have up to 60 minutes to approve the transaction after the subscription payment is requested.

2. Confirming the Enrollment

   As soon as the enrollment is confirmed by the customer in their banking app, the enrollment status is modified from pending to accepted and a Status Update Notification is sent to the URL defined in your merchant configuration. Check the notification example below:

   operation=enrollment_status_change&notification_type=update&merchant_enrollment_code=99911110104

   To ensure efficient and compliant interactions, EBANX allows merchants to confirm a user's enrollment status before sending multiple notifications or processing transactions.

   So before requesting any payments, using the ID provided in merchant_enrollment_code, call the /ws/userenrollments/query endpoint to get the latest status of the enrollment.

   Check the example:

   curl -X POST 'https://api.ebanx.com/ws/userenrollments/query' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "{{integration_key}}",
       "payment_type_code": "upi-collect-autopay",
       "enrollment": {
           "country": "in",
           "merchant_enrollment_code": "{{unique_enrollment_code}}"
       }
   }'

   A successful request will return a JSON response like the one below, with a status of accepted for the enrollment approved by the customer. Other possible enrollment statuses include not accepted, paused, pending, expired, not_found and revoked, depending on the actions taken by the merchant or customer.

   {
      "status": "SUCCESS",
      "enrollment": {
          "status": "accepted"
      }
   }

   If your enrollment has the status accepted, you can start requesting the recurring payments following the instructions on the Pre-Debit Notification and Recurring Payment Request pages.

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at integration@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.