Skip to main content
UPI Recurring

UPI (Unified Payments Interface) is a real-time payment system that allows for instant bank transfers. This guide will walk you through the steps to integrate Recurring UPI payments with EBANX, allowing you to set up regular subscription-based payments for your customers.

How it works​

To integrate recurring UPI transactions, you will need to follow three main steps:

  1. Subscription enrollment - Register the subscription to establish the customer's recurring payment setup.
  2. Pre-debit notification - Notify the customer before initiating the payment, as required by Indian regulations.
  3. Payment request - Request the actual payment after ensuring the pre-debit notification has been successfully acknowledged.

Requirements​

  • API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
  • Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.

Instructions​

Follow the steps below.

  1. Select your environment

    Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

    https://sandbox.ebanx.com/ws/direct

  2. Subscription enrollment parameters

    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. Once the process is complete, the customer will be enrolled for the recurring payment cycle. You’ll need to specify the following parameters in your enrollment request


    Essential parameters

    ParameterDescription
    operationSet to enrollment
    integration_keyYour EBANX integration key
    payment_type_codeSet to upi-collect-autopay

    Subscription parameters

    ParameterDescription
    enrollment.merchant_enrollment_codeUnique identifier associated with the subscription.
    enrollment.countryTwo-letter country code. Set to in for India.
    enrollment.back_urls.successCallback URL for successful response.
    enrollment.back_urls.failureCallback URL for failure response.
    subscription.subscription_nameDescription for the subscription.
    subscription.expiration_dateExpiration date of the subscription.
    subscription.frequencyFrequency for charging the subscription.
    ondemand monthly biweekly weekly
    subscription.recurrence_ruleMust be on if subscription frequency is:
    monthly, biweekly or weekly
    subscription.recurrence_valueMandatory if subscription frequency is monthly, biweekly or weekly.
    If weekly, 1 to 7,
    If biweekly, 1 to 16,
    If monthly 1 to 31.
    subscription.min_amountMinimum amount (per payment) during the validity of subscription plan, (In INR currency)
    subscription.max_amountMaximum amount (per payment) during the validity of the subscription plan, (In INR currency)
    upi.vpaSubscription payer UPI ID.
    Standard format is 'payer@vpa'.
    Mandatory if payment_type_code is
    upi-collect-autopay.

    Addition information​

    • To set a fixed subscription amount, use equal values for the following:
      • subscription.min_amount and subscription.max_amount
    • The following params 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 subscription.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.
      • For more flexibility, consider using the ondemand frequency.

  3. Enrollment request

    Use the following example to initiate an enrollment request.

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

  4. Enrollment Response

    A successful request will return a JSON response like the one below.
    {
      "status": "SUCCESS",
      "enrollment": {
        "merchant_enrollment_code": "1234567ABCD",
        "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"
          }
      }
    }

    Tips​

    For subscriptions with payment amounts under 15,000 INR, auto-debit can be enabled for subsequent payments.

    • This means that for following transactions under 15,000 INR, PIN authentication for UPI transactions will not be required.
    • However, the first payment must be executed within 5 minutes of the initial enrollment.

    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.

  5. Pre-debit notification

    This is a mandatory step that must be sent to the user before initiating a payment. This notification informs the customer about the upcoming transaction, ensuring they are aware of the payment being applied to their account. The pre-debit notification is a regulatory requirement for all recurring payments.

    To send a pre-debit notification, use the /ws/customerenrollment-notify endpoint. This will trigger a notification to the customer, allowing them to be informed and prepared for the payment.

    Important: The subscription payment can only proceed once the pre-debit notification has been successfully sent and acknowledged by the customer with a "status": "notified" response.


    Parameters

    ParameterDescription
    integration_keyYour EBANX integration key.
    amountAmount for the upcoming payment.
    merchant_enrollment_codeUnique enrollment code defined when subscription was registered.
    payment_execution_dateDate and time for the upcoming payment.
    Expected format: yyyy-mm-dd hh:mm:ss.

    Sample Request

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/customerenrollment-notify/' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "Your EBANX integration key",
        "amount": "1000",
        "merchant_enrollment_code": "1234567ABCD",
        "payment_execution_date": "2024-08-01 12:00:00"
      }'

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

    {
      "status": "SUCCESS",
      "notification": {
        "hash": "ac682d9c3b5a2f90150bjcbabe89b933f954e616fbd19e0dff99339f7586881f4e397ca7dd88baba9715d40f39562e8040c1898a551143574aa0f93fc07a4c6e",
        "amount": "1000",
        "status": "notified",
        "payment_execution_date": "2024-08-01 12:00:00"
      }
    }

    Mandatory Wait Period​

    A mandatory wait period exists between the pre-debit notification to the user and the initiation of the subscription payment.

    • The payment can only be initiated once a successful response, with "status": "notified" is received.
    • For subscriptions with a frequency of ondemand, the wait period must be at least 24 hours.
    • For subscriptions with a frequency of monthly, biweekly, or weekly, the wait period must be at least 48 hours.
    • Subscription payment attempts made without a prior pre-debit notification to the user, or within a wait period shorter than the required duration, will be declined.

  6. Define payment parameters

    The subscription payment request follows the same standards as the ws/direct payment requests, with the addition of specific parameters related to the subscription. These parameters link the payment to the corresponding subscription, ensuring that the recurring payment is properly processed.


    Essential parameters

    Basicparameters:
    integration_keyYour EBANX integration key
    operationSet to request

    Payment parameters

    Paymentparameters:
    payment.namePayer full name
    payment.emailCustomer email
    payment.countryTwo-letter country code. Set to in for India
    payment.merchant_payment_codeUnique code for the payment
    payment.currency_codeSet to INR
    payment.amount_totalPayment amount
    metadata.merchant_enrollment_codeUnique identifier associated with the subscription
    To learn more about parameters and view examples, please refer to the
    API Reference Guide chevron_right

  7. Payment request

    Use the ws/direct endpoint to initiate a payment request, ensuring the payment is correctly linked to the corresponding subscription.

    Sample request:

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "Your EBANX integration key",
        "operation": "request",
        "payment": {
        "name": "John Doe",
        "email": "email@example.com",
        "country": "in",
        "payment_type_code": "upi-collect-autopay",
        "merchant_payment_code": "PMT1234567BC",
        "currency_code": "INR",
        "amount_total": 1000,
        "metadata": {
          "merchant_enrollment_code": "1234567ABCD"
        }
      }
    }'

    A successful request returns a response like the example below.

    {
      "payment": {
        "hash": "66a22a492540fe35c3d6479aa88551d844ea66de7c193bd1",
        "country": "in",
        "merchant_payment_code": "PMT1234567BC",
        "status": "PE",
        "open_date": "2024-08-02 13:00:00",
        "amount_br": "1000.00",
        "amount_ext": "1000.00",
        "amount_iof": "0.00",
        "currency_rate": "1.0000",
        "currency_ext": "INR",
        "due_date": "2024-07-28",
        "instalments": "1",
        "payment_type_code": "upi-collect-autopay",
        "customer": {
          "email": "email@example.com",
          "name": "John Doe",
        },
      },
      "status": "SUCCESS"
    }
    At this stage, the payment will appear as pending (PE) in your
    EBANX Dashboardchevron_right

  8. Monitor payment for status changes

    Notifications

    Status

    • After receiving a notification that status has changed, retrieve the payment status.

    • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).

  9. Congratulations!

    You have succesfully integrated UPI Recurring.

    For more information, refer to the
    Direct API reference guidechevron_right

Resources​

Use the following resources when testing in your sandbox environment.

Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right
Debit Card Icon

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

Help Image

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