Skip to main content

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.


UPI Autopay Enrollment Flow

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

    Your title

    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

    ParameterRequirementDescription
    integration_keyRequiredYour integration key
    payment_type_codeRequiredMust be upi-collect-autopay
    operationRequiredMust be enrollment

    Enrollment data

    ParameterRequirementDescription
    enrollment.merchant_enrollment_codeRequiredUnique identifier associated with the enrollment.
    enrollment.countryRequiredTwo-letter country code. Set to "in" for India.
    enrollment.back_urls.successRequiredCallback URL for a successful response.
    enrollment.back_urls.failureRequiredCallback URL for a failure response.
    subscription.subscription_nameRequiredDescriptor 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_dateRequiredDefines when the enrollment is no longer valid and no further payments will be charged.
    subscription.frequencyRequiredThe billing cycle of the enrollment. Available frequencies are: weekly, biweekly, monthly, and ondemand.
    subscription.recurrence_valueOptional (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_amountRequiredMinimum amount (per payment) during the validity of the subscription plan (in INR currency).
    subscription.max_amountRequiredMaximum amount (per payment) during the validity of the subscription plan (in INR currency).
    upi.vpaRequiredSubscription 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 second debit request .
    • 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?

Help Image

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