Skip to main content

Card Recurring

Card recurring payments in India enable merchants to securely process subscription-based transactions using digital authorization and tokenization. This guide will help you integrate and manage recurring payments while ensuring compliance with Reserve Bank of India (RBI) regulations.

How it works​

  • Customer signs up - The customer enters their card details and agrees to recurring payments via a secure one-time authentication (e.g., OTP).
  • Payment setup - EBANX creates a digital agreement (e-mandate) with the customer’s bank, setting the amount and schedule.
  • Pre-payment alert - The customer gets a notification (SMS/email) at least 24 hours before each charge, showing the amount and date.
  • Automatic charging - EBANX processes the payment on the scheduled date using a secure token instead of card details.
  • Confirmation - Both the merchant and customer get notified once the payment is complete.

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. Request a subscription + first charge

    Collect the necessary parameters to configure your request.

    ParameterDescription
    operationSet to enrollment
    integration_keyYour EBANX integration key
    payment_type_codeSet to creditcard or debitcard

    Customer information

    ParameterDescription
    namePayer full name
    emailCustomer email
    phone_numberCustomer phone number, in full international format
    addressStreet name, character limit 100
    street_numberStreet number, character limit 30
    street_complementComplement information, character limit 100
    cityAbbreviation (DL, JK, etc)
    stateAbbreviation (UP, HR, etc)
    zipcode6-digit zipcode

    Subscription details

    ParameterDescription
    enrollment.merchant_enrollment_codeUnique identifier associated with the subscription. (Character limit: 254)
    enrollment.countryTwo-letter country code. Set to in for India.
    subscription.subscription_nameDescription for the subscription.
    subscription.expiration_dateValidity for the subscription.
    subscription.frequencyFrequency rule for charging the subscription.
    Accepted values:
    daily weekly fortnightly monthly bimonthly quarterly halfyearly yearly ondemand
    subscription.min_amountMinimum amount (per charge) during the validity of the 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)

    Charge parameters

    ParameterDescription
    payment.namePayer full name.
    payment.emailCustomer email.
    payment.countrySet to in for India.
    threeds_forceTrue
    payment.merchant_payment_codeUnique code for the payment.
    payment.currency_codeISO-4217 Currency code transaction. Supported value: INR.
    payment.merchant_payment_codeUnique code for the payment.
    payment.amount_totalCharge amount (Minimum 1.00 INR)
    payment.enrollment.merchant_enrollment_codeUnique identifier for the subscription, with a maximum character limit of 254.
    payment.enrollment.customer_notify_hashUnique identifier for the Pre-debit notification, returned as a hash in the response upon successful notification delivery.sent.
    Subscription Frequency Rules

    Pre-defined subscription.frequency values dictate when charges can be executed but do not automate subsequent actions. Pre-debit notifications and charge executions must still be managed. Attempts outside the schedule will be declined, but missed windows do not affect subscription status. Charges can proceed in the next cycle. For more flexibility, use ondemand as the frequency.

    Shared Subscription Details

    The values in subscription.subscription_name, subscription.expiration_date, and subscription.frequency will be sent to the user via SMS by their issuing bank.

    Fixed Subscription Amount

    To set a fixed amount for a subscription request, send subscription.min_amount and subscription.max_amount with the same value.

  3. Sample request

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/userenrollment' \ // Enrollment endpoint.
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "********************************ebxlfe",
        "operation": "request",
        "mode": "full",
        "payment": {
            "name": "Sam",
            "email": "sam@xyz.com",
            "birth_date": "12/04/1979",
            "document": "EF5680710",
            "address": "Nirvana society",
            "street_number": "2993",
            "street_complement": "CJ 5",
            "city": "DL",
            "state": "DL",
            "zipcode": "110017",
            "country": "in",
            "phone_number": "4111111111",
            "payment_type_code": "creditcard",
            "instalments": "1",
            "amount_total": 1,
            "currency_code": "INR",
            "merchant_payment_code": "testmandate00101",
            "card": {
                "card_number": "13452******0495",
                "card_name": "Sam Sh",
                "card_due_date": "08/2050",
                "card_cvv": "***",
                "threeds_force": true
            },
            "enrollment": {
                "country": "in",
                "merchant_enrollment_code": "testenrollment00101",
                "email": "sam@xyz.com",
                "back_urls": {
                    "success": "https://developer.ebanx.com/",
                    "failure": "https://google.com.br"
                },
                "subscription": {
                    "subscription_name": "testsub00101",
                    "expiration_date": "2024-12-31",
                    "min_amount": "1",
                    "max_amount": "1000",
                    "frequency": "ondemand"
                }
            }
        }
    }

    Auto-Debit and 2FA Requirements

    For subscriptions with expected charge amounts below INR 15,000, auto-debit can be enabled for subsequent charges. This exempts users from two-factor authentication (2FA) (OTP authentication) for future transactions under INR 15,000. However, charges exceeding INR 15,000 will always require user authentication (2FA) for approval.

  4. Pre debit notification to user

    Before processing a recurring subscription charge, you must send a pre-debit notification to the user. This step informs the customer about the upcoming charge, ensuring transparency and compliance with payment regulations. The notification must be sent at least 24 hours before the charge is executed to prevent declines.

    The following parameters are required:​

    ParameterTypeDescription
    integration_keyStringYour unique and secret integration key, used to authenticate the request.
    amountStringThe amount of the upcoming charge, in the format "1000" for 1000 units of the currency (e.g., cents for USD).
    merchant_enrollment_codeStringThe unique enrollment code assigned when the subscription was registered.
    payment_execution_dateStringThe date and time of the upcoming charge, in the format yyyy-mm-dd hh:mm:ss (e.g., "2024-08-01 12:00:00").

    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": "testenrollment00101",
       "payment_execution_date": "2024-08-01 12:00:00"
    }'

    A successful request returns a JSON response like this:​

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

    You must wait at least 24 hours after sending the pre-debit notification before initiating the subscription charge.

    • The charge can only proceed after receiving a response with status : notified.
    • Attempting a charge without this prior notification—or within a shorter wait period—will result in rejection.

    Send the notification well in advance of the payment_execution_date. Verify the response to ensure the notification was successful before scheduling the charge.

  5. Process a subscription payment

    The next step after sending a successful pre-debit notification and observing the mandatory 24-hour wait period is to process the subscription payment. This request adheres to the standard format used for ws/direct charge requests, with the addition of specific parameters that link the charge to the subscription. This ensures proper tracking and compliance with notification requirements.

    Parameters​

    To successfully process a subscription payment, you need to include both basic parameters (common to all ws/direct requests) and charge-specific parameters (unique to subscription payments). These are outlined below:

    Basic Parameters​

    ParameterDescription
    integration_keyYour unique and secret integration key, used to authenticate the request.
    operationThe operation type. Must be set to "request" for charging a subscription.

    Charge Parameters​

    ParameterDescription
    payment.nameThe full name of the payer.
    payment.emailThe customer's email address.
    payment.countryTwo-letter country code (e.g., "in" for India).
    payment.merchant_payment_codeA unique code identifying this specific payment.
    payment.currency_codeThe ISO-4217 currency code for the transaction (e.g., "INR").
    payment.amount_totalThe total amount to be charged.
    payment.enrollment.merchant_enrollment_codeThe unique identifier for the subscription (max 254 characters).
    payment.enrollment.customer_notify_hashThe hash received from the successful pre-debit notification response.

    Sample request​

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
     "integration_key": "{{integration_key}}",
     "operation": "request",
     "payment": {
       "name": "Sam",
       "email": "sam@xyz.com",
       "country": "in",
       "payment_type_code": "creditcard",
       "merchant_payment_code": "testmandate00101",
       "currency_code": "INR",
       "amount_total": 1000,
       "enrollment": {
         "merchant_enrollment_code": "testenrollment00101",
         "customer_notify_hash": "561eb4005d491a7eb009af3f09355969b0f3ed51dda6f3bd99e50c4c41ab799e337a6cb9295cf4028a9ceccdc299850a07ecb123f0fef14bdcc6e7679633956d"
       }
     }
    }'

    Sample response​

    A successful request returns a JSON response like this:

    {
     "payment": {
       "hash": "66a22a492540fe35c3d6479aa88551d844ea66de7c193bd1",
       "country": "in",
       "merchant_payment_code": "testmandate00101",
       "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": "creditcard",
       "customer": {
         "email": "sam@xyz.com",
         "name": "Sam"
       }
     },
     "status": "SUCCESS"
    }

    Upon success, the payment will appear as Pending (PE) in your EBANX Dashboard.

  6. Using EBANX to manage pre-debit notification and charging

    If you prefer not to manage the pre-debit notification and the subsequent charge as two separate API calls, Ebanx offers a convenient option to handle both in a single request. By submitting a charge request with specific subscription parameters, Ebanx will automatically manage the notification and execute the charge after the mandatory 24-hour wait period. This simplifies your integration while ensuring compliance with notification requirements.

    Parameters This request uses the standard parameters for a ws/direct charge request, with the addition of the enrollment object to specify the subscription details. Below are the key parameters to include:

    Parameters​

    ParameterDescription
    integration_keyYour EBANX integration key.
    operationSet to request.
    modeSet to full for a complete payment request.
    payment.nameCustomer's full name.
    payment.emailCustomer's email address.
    payment.birth_dateCustomer's birth date in dd/mm/yyyy format.
    payment.documentCustomer's document number.
    payment.addressCustomer's street address.
    payment.street_numberStreet number.
    payment.street_complementAdditional address information.
    payment.cityCity name.
    payment.stateState or province.
    payment.zipcodePostal code.
    payment.countrySet to in for India.
    payment.phone_numberCustomer's phone number.
    payment.payment_type_codePayment method (e.g., visa).
    payment.instalmentsNumber of installments (e.g., 1).
    payment.amount_totalTotal amount to be charged.
    payment.currency_codeISO-4217 currency code (e.g., INR).
    payment.merchant_payment_codeUnique code for this payment.
    payment.enrollment.merchant_enrollment_codeUnique identifier for the subscription.
    For a complete list of parameters, refer to the
    Direct API reference guidechevron_right

    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",
     "mode": "full",
     "payment": {
       "name": "Sam",
       "email": "sam@xyz.com",
       "birth_date": "12/04/1979",
       "document": "xyzhin",
       "address": "AV MIRACATU",
       "street_number": "2993",
       "street_complement": "CJ 5",
       "city": "DL",
       "state": "DL",
       "zipcode": "110017",
       "country": "in",
       "phone_number": "4111111111",
       "payment_type_code": "visa",
       "instalments": "1",
       "amount_total": 1,
       "currency_code": "INR",
       "merchant_payment_code": "testAutoNotifyCard140101",
       "enrollment": {
         "merchant_enrollment_code": "testenrollment20250107X02"
       }
     }
    }'

    Sample response​

    A successful request will return a JSON response similar to this:

    {
        "payment": {
            "hash": "67869f5cf7486ad470a84cb898ae625e20db248eb262dca9",
            "country": "in",
            "merchant_payment_code": "testAutoNotifyCard140101",
            "order_number": null,
            "status": "PE",
            "status_date": null,
            "open_date": "2025-01-14 17:31:08",
            "confirm_date": null,
            "transfer_date": null,
            "amount_br": "1.00",
            "amount_ext": "1.00",
            "amount_iof": "0.00",
            "amount_ext_requested": "1.00",
            "currency_rate": "1.0000",
            "currency_ext": "INR",
            "due_date": "2025-01-17",
            "instalments": "1",
            "payment_type_code": "visa",
            "details": {
                "billing_descriptor": "EBN*DEMONSTRATION"
            },
            "transaction_status": {
                "acquirer": "EBANX",
                "code": "PENDING_AUTHENTICATION",
                "description": "Pending Authentication",
                "description_code": "PENDING_AUTHENTICATION"
            },
            "pre_approved": false,
            "capture_available": false,
            "customer": {
                "document": "EF5680710",
                "email": "sam@xyz.com",
                "name": "Sam",
                "birth_date": "1979-04-12"
            },
            "card_unique_id": "123456789U",
            "requested_currency": "INR",
            "threedsecure": {
                "has_threeds": false
            },
            "currency_ext_base": "INR",
            "card_issuer_country": "IN",
            "payment_execution_date": "2025-01-15 17:36:09"
        },
        "status": "SUCCESS"
    }

    Considerations

    • You must provide the unique merchant_enrollment_code associated with the subscription to ensure the notification and charge are linked correctly.

    • After submitting the request, the payment will appear as "pending" ("PE") in your EBANX Dashboard for 24 hours. The charge will be executed automatically after this period.

    • You are responsible for managing the recurring debit logic, including the frequency of deductions. EBANX handles only the notification and initial charge for this request.

    • If two-factor authentication (2FA) is required, the customer must complete it. If they fail to do so, the payment will be automatically canceled.

  7. 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).

  8. Manage Enrollment Status

    To effectively manage subscriptions, you need to monitor and respond to changes in enrollment status. EBANX provides two reliable methods to keep you updated:

    1. Asynchronous notifications:

    EBANX sends real-time updates to your specified endpoint whenever an enrollment status changes (e.g., accepted, paused, or resumed).

    Sample notification​

    operation=enrollment_status_change&notification_type=update&merchant_enrollment_code=testenrollment00104

    2. Actives status querying:

    Retrieve the latest enrollment status on-demand before actions like notifications or transactions. This ensures you’re working with the most current data from EBANX.

    Endpoint:

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

    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": "query",
        "payment_type_code": "creditcard",
        "enrollment": {
            "merchant_enrollment_code": "testenrollment00101",
            "country": "in"
        }
      }

    Sample response (Accepted):​

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

    Sample response (Paused):​

    {
        "status": "SUCCESS",
        "enrollment": {
            "status": "paused",
            "email": ""
        }
    }

    Sample response (Resumed):​

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

    Combine both methods for optimal management—use notifications for instant updates and querying for on-demand checks.

  9. Cancel a subscription (Revoke enrollment)

    Canceling a subscription (revoking an enrollment) is a straightforward process. This action immediately terminates the subscription, preventing further charges or notifications. Use this step when a customer requests to end their subscription or when you need to stop recurring payments for any reason.

    Send a Cancellation Request:​

    • Use the operation: "cancel" parameter to initiate the cancellation.
    • Include the merchant_enrollment_code to specify the subscription to be canceled.
    • Optionally, include the customer's email and country for verification.

    Confirm the Response:​

    • A successful cancellation will return a status of "revoked".

    Cancellation is irreversible

    Cancellation is immediate and irreversible. Ensure you have the correct merchant_enrollment_code before proceeding.

    Sample request​

    Use the following JSON structure to send a cancellation request:

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/userenrollment' \ // Enrollment endpoint.
      --header 'Content-Type: application/json' \
      --data '{
       "integration_key": "your_ebanx_integration_key",
       "operation": "cancel",
       "payment_type_code": "creditcard",
       "enrollment": {
           "merchant_enrollment_code": "testenrollment00101",
           "email": "sam@xyz.com",
           "country": "IN"
       }
    }

    Sample response​

    A successful cancellation will return the following JSON response:

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

  10. Congratulations!

    You have succesfully integrated Card 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: