Version: current

Recurring UPI with Direct API

About this guide

By following this basic integration guide, you will understand how you can start accepting recurring UPI payments in India using EBANX Direct API.

To complete a recurring transaction in India you will, basically, need to call three of our APIs; /ws/userenrollment/ to request a subscription registration, /ws/customerenrollment-notify/ one to trigger the mandatory pre debit notification to user, and /ws/direct/ to request the charge.

Availability

Recurring UPI integration for merchants offering digital products & services through Direct API is available to the following countries:

  • India

If you are not integrated with EBANX Direct API yet, please take a look in this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

Before starting your integration, please make sure that you have:

  1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
  2. Recurring UPI enabled in your EBANX Dashboard.

How it works

To complete recurring UPI integration through EBANX Direct API, please follow the steps below.

  1. Enable recurring UPI

    Recurring UPI availability may vary depending on your contract. So the first step is to check if it is active in your EBANX dashboard.

    All set? We can go ahead to the next step, otherwise, please get in touch with our integration specialists.

  2. Configure your Notification URL

    For your recurring UPI flow, you will receive webhook notifications for subscription status updates (paused, revoked), pre-debit notifications to the user, and payment transaction events. Each time a webhook notification is received we will require you to query us for the latest status . Please refer to the instructions for configuring your URL Notifications Notifications.

  3. Request a Subscription

    Basic parameters

    ParameterDescription
    operationOperation must be enrollment
    integration_keyYour unique and secret integration key
    payment_type_codeFor recurring payments in India the types currently available are upi-collect-autopay

    Subscription details

    ParameterDescription
    enrollment.merchant_enrollment_codeUnique identifier associated with the subscription. (character limit : 254)
    enrollment.countryTwo-letter country code - in for India.
    subscription.subscription_nameDescription for the subscription.
    subscription.expiration_dateValididy for the subscription.
    subscription.frequencyFrequency rule for charging the subscription. Values accepted are: ondemand, monthly, biweekly, weekly.
    subscription.recurrence_ruleMust be on if subscription.frequency is monthly, biweekly or weekly.
    subscription.recurrence_valueMandatory for defining rules if subscription.frequency is monthly, biweekly or weekly. Acceepted values are the following: for weekly 1 to 7, for biweekly 1 to 16, for monthly 1 to 31.
    subscription.min_amountMinimum amount (per charge) during the validity of subscription plan, in INR. (should start from INR 1)
    subscription.max_amountMaximum amount (per charge) during the validity of the subscription plan, in INR. (max amount INR 100000)
    upi.vpaSubscription payer UPI ID. Expected standard format is 'payer@vpa'. Mandatory if payment_type_code is upi-collect-autopay.
    info

    Values shared in the following parameters on subscription object: subscription_name, expiration_date, frequency, min_amount and max_amount; will be displayed to the user on its UPI App along with the subscription authentication request.

    note

    The values for pre-defined frequencies accepted on subscription.frequency are considered for setting the rules for when the charges for the subscription can be executed. This must not be considered as an automation of the subsequent actions required for charging a subscription. The pre debit nofitication to user and charge subscription actions will still be required and must be managed for all subsequent transactions. Charge attempts for subscriptions with a pre-defined rules outside such rules will be declined. In cases of skipping or missing the time window for such patter, the subscription status will not be altered or impacted, and the charge attempts can be normally handled in the following window. For more flexibility on handling your subscriptions charges, it is recommended to set the ondemand value for subscription frequency.

    tip

    To set a fixed amount for the subscription request, values for subscription.min_amount and subscription.max_amount should be send with an equal amount information.

    4. Request example:

    curl -L -X POST 'https://sandbox.ebanxpay.com/ws/userenrollment/' \
    -H 'Content-Type: application/json' \
    --data-raw '
    {
    "integration_key": "{{integration_key}}",
    "operation": "enrollment",
    "payment_type_code": "upi-collect-autopay",
    "enrollment": {
    "merchant_enrollment_code": "1234567ABCD",
    "email": "email@example.com",
    "country": "IN",
    "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": "1234567ABCD",
    "email": "email@example.com",
    "country": "IN",
    "subscription": {
    "subscription_name": "Descriptor of the subscription.",
    "expiration_date": "2025-12-30",
    "frequency": "ondemand",
    "min_amount": "1",
    "max_amount": "20000"
    },
    "upi": {
    "vpa": "payer@vpa"
    }
    }
    tip

    For subscriptions with expected charge amounts lower than INR 15.000, the auto-debit can be enabled for the subsequent charges. The auto-debit will exempt the requirement for 2FA on user end (PIN authentication for UPI transactions) for the succeding transactions with amount under 15.000 INR. For that, the first charge must be executed within 5 minutes from mandate registration. Important: This will not exempt the subsequent charges from the mandatory pre debit notification to the user. Charges above INR 15,000 will always require user authentication (2FA) for approval. In these cases, the maximum time for users to confirm the transaction is up to 60 minutes after the Subscription Charge was requested.

    Top 5 Third Party App VPA examples: PhonePe VPA: @ybl / @ibl / @axl Google Pay VPA: @okaxis PayTM VPA: @paytm Amazon Pay VPA: @apl

    Top 5 bank VPA examples: State Bank of India: @sbi ICICI Bank: @icici HDFC Bank: @hdfcbank Axis Bank: @axisbank Punjab National Bank: @pnb

    Please note these are just the most common VPA addresses likely to be visible but it can vary bank to bank.

  4. Pre debit notification to user

    Parameter description

    ParameterDescription
    integration_keyYour unique and secret integration key.
    amountAmount for the upcoming charge being notified.
    merchant_enrollment_codeUnique enrollment code defined when subscription was registered.
    payment_execution_dateTime and date for the upcoming charge being notified. Expected format: yyyy-mm-dd hh:mm:ss.

    Request example:

    curl -L -X POST 'https://sandbox.ebanxpay.com/ws/customerenrollment-notify/ ' \
    -H 'Content-Type: application/json' \
    --data-raw '{
    "integration_key": "{{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"
    }
    }
    caution

    There is a mandatory wait period between the pre-debit notification to the user and the initiation of the subscription charge, which can only occur after receiving a successful response with the "status": "notified.". Customer needs to be notified 24hrs prior to the debit happening. Subscription charge attempts without a prior pre-debit notification to the user, or made within a shorter-than-required wait period, will be declined.

  5. Charge Subscription

    The request for charging a Subscription will follow the same standards for the ws/direct charge requests, with the addition of some specific parameters related to the Subscription to which the charge belongs.

    Basic parameters

    Basicparameters:
    integration_keyYour unique and secret integration key.
    operationOperation must be request.

    Charge parameters

    Chargeparameters:
    payment.namePayer full name.
    payment.emailCustomer email.
    payment.countryTwo-letter country code - in for India.
    payment.merchant_payment_codeUnique code for the payment.
    payment.currency_codeISO-4217 Currency code transaction. Supported value: INR.
    payment.amount_totalCharge amount
    payment.enrollment.merchant_enrollment_codeUnique identifier associated with the subscription.(character limit : 254)
    payment.enrollment.customer_notify_hashPre-debit notification. This is the hash received in the response when a pre-debit notification is successfully sent.

    Request example:

    curl -L -X POST 'https://sandbox.ebanxpay.com/ws/direct' \
    -H 'Content-Type: application/json' \
    --data-raw '{
    "integration_key": "{{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,
    "enrollment": {
    "merchant_enrollment_code": "testautopay010811",
    "customer_notify_hash": "561eb4005d491a7eb009af3f09355969b0f3ed51dda6f3bd99e50c4c41ab799e33 7a6cb9295cf4028a9ceccdc299850a07ecb123f0fef14bdcc6e7679633956d"
    }
    }
    }'

    A successful request will return a JSON response like the one 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",
    "installments":"1",
    "payment_type_code":"upi-collect-autopay",
    "customer":{
    "email":"email@example.com",
    "name":"John Doe"
    }
    },
    "status":"SUCCESS"
    }
    info

    After receiving a successful pre debit notification to the user and meeting the mandatory wait period requirement, a total of 3 attempts for charging the transaction will be allowed. At this point you have a pending (PE) payment in your EBANX Dashboard.

    6. info

    The complete API reference for the end-point ws/direct can be found here. We strongly recommend you to take a look in all the available options.

  6. Wait for the payment

    As soon as EBANX identifies that the payment was confirmed, payment status is modified from pending to confirmed.

    If, for cases where 2FA are required for approving the transaction, your customers don't conclude the payment, it will be automatically canceled.

  7. Query Enrollment

    During any enrollment status change, EBANX will notify merchant via our async notification, for example:

    operation=enrollment_status_change&notification_type=update&merchant_enrollment_code=testenrollment00104

    Additionally, EBANX supports merchants to actively retrieve user enrollment status before performing consecutive notification and transaction.

    Endpoint: https://api.ebanx.com/ws/userenrollments/query

    Sample request:

    {
    "integration_key":"DEMO_KEY",
    "operation":"query",
    "payment_type_code":"upi-collect-autopay",
    "enrollment":{
    "merchant_enrollment_code":"testMandateProdUPI131101",
    "country":"in"
    }
    }

    Response:

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

  8. Revoke an Enrollment

    If you require to revoke/cancel a subscription for a customer , you can simply send us a request with operation : "cancel", this will immediately cancel the subscription.

    Sample request:

    {
    "integration_key": "6e590512de1c170a4fa943025e3fb946ebxlfe",
    "operation": "cancel",
    "payment_type_code": "upi-collect-autopay",
    "enrollment": {
    "merchant_enrollment_code": "1234567ABCD",
    "email": "email@example.com",
    "country": "IN"
    }
    }

    Response:

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

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

  • If you’re not our partner yet and would like to know more about our prices and conditions please fill ou this form and our comercial team will get in touch with you.
  • In case you’re already our partner please get in touch with our support team at integration@ebanx.com.
Edit this page
Last updated on by FlavioCostaeSilva
On this page