Card Recurring

Recurring Alternatives Bundle

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.

   SandboxProduction

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

2. Request a subscription + first charge

   Collect the necessary parameters to configure your request.

   Parameter	Requirement	Description
   integration_key	Required	Your EBANX integration key
   payment.payment_type_code	Required	Set to creditcard or debitcard

   
   

   Subscription details

   Parameter	Requirement	Description
   payment.enrollment.merchant_enrollment_code	Required	Unique identifier associated with the subscription. (Character limit: 254)
   payment.enrollment.subscription.subscription_name	Required	Descriptor of the service being provided, which will be displayed in the customer's app. No special characters allowed. Maximum characters allowed - 50.
   payment.enrollment.subscription.expiration_date	Required	Defines when the enrollment is no longer valid and no further payments will be charged
   payment.enrollment.subscription.frequency	Required	The billing cycle of the enrollment. Accepted values: weekly monthly yearly ondemand
   payment.enrollment.subscription.min_amount	Required	Minimum amount (per payment) during the validity of the subscription plan (in INR currency).
   payment.enrollment.subscription.max_amount	Required	Maximum amount (per payment) during the validity of the subscription plan (in INR currency).

   
   

   Charge parameters

   Parameter	Requirement	Description
   payment.name	Required	Customer's full name Note: Minimum 5 characters, alphabets only
   payment.email	Required	Customer's email.
   payment.phone_number	Required	Customer's phone Note: Minimum 8 digits, maximum 10 digits, numbers only
   payment.address	Required	Customer's address Note: Minimum 3 characters
   payment.street_number	Optional	Customer's street number
   payment.street_complement	Optional	Complement information
   payment.city	Required	Customer's city Note: Minimum 3 characters, alphabets only
   payment.state	Required	Customer's state Note: Refer this for state list. Either use state code or state name
   payment.zipcode	Required	Customer's zipcode or pincode Note: Must be 6 digits, numbers only
   payment.country	Required	Set to in for India
   payment.merchant_payment_code	Required	Unique code for the payment
   payment.currency_code	Required	Set to INR
   payment.amount_total	Required	Payment amount (Minimum 1.00 INR)
   payment.card.threeds_force	Required	set to true
   payment.card.card_number	Required	16 digit card number
   payment.card.card_name	Required	Card holder's name
   payment.card.card_due_date	Required	Expiry date of card (in mm/yyyy format)
   payment.card.card_cvv	Required	CVV number of the card

   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/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_ebanx_integration_key",
       "payment": {
           "name": "John Doe",
           "email": "john.doe@example.com",
           "address": "Nirvana society",
           "street_number": "2993",
           "street_complement": "CJ 5",
           "city": "Bangalore",
           "state": "Karnataka",
           "zipcode": "560087",
           "country": "in",
           "phone_number": "4111111111",
           "payment_type_code": "creditcard",
           "amount_total": 1,
           "currency_code": "INR",
           "merchant_payment_code": "<{merchant_payment_code_here}>",
           "card": {
               "card_number": "134521******0495",
               "card_name": "John Doe",
               "card_due_date": "08/2050",
               "card_cvv": "***",
               "threeds_force": true
           },
           "enrollment": {
               "merchant_enrollment_code": "<{merchant_enrollment_code_here}>",
               "back_urls": {
                   "success": "https://developer.ebanx.com/",
                   "failure": "https://google.com.br"
               },
               "subscription": {
                   "subscription_name": "<{subscription_name_here}>",
                   "expiration_date": "2034-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

   Parameter	Requirement	Description
   integration_key	Required	Your unique and secret integration key, used to authenticate the request.
   amount	Required	Payment amount
   merchant_enrollment_code	Required	The unique enrollment code assigned when the subscription was registered.
   payment_execution_date	Required	The date and time of the recurring charge, in the format yyyy-mm-dd hh:mm:ss (should be at least 24 hours later)

   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": "<{merchant_enrollment_code_here}>",
      "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

   Parameter	Requirement	Description
   integration_key	Required	Your unique and secret integration key, used to authenticate the request.
   payment.payment_type_code	Required	Set to creditcard or debitcard

   Charge Parameters

   Parameter	Requirement	Description
   payment.name	Required	Customer's full name Note: Minimum 5 characters, alphabets only
   payment.email	Required	Customer's email.
   payment.phone_number	Required	Customer's phone Note: Minimum 8 digits, maximum 10 digits, numbers only
   payment.address	Required	Customer's address Note: Minimum 3 characters
   payment.street_number	Optional	Street number
   payment.street_complement	Optional	Complement information
   payment.city	Required	Customer's city Note: Minimum 3 characters, alphabets only
   payment.state	Required	Customer's state Note: Refer this for state list. Either use state code or state name
   payment.zipcode	Required	Customer's zipcode or pincode Note: Must be 6 digits, numbers only
   payment.country	Required	Set to in for India.
   payment.merchant_payment_code	Required	Unique code for the payment.
   payment.currency_code	Required	Set to INR
   payment.amount_total	Required	The total amount to be charged in INR
   payment.enrollment.merchant_enrollment_code	Required	The unique identifier for the subscription
   payment.enrollment.customer_notify_hash	Required	The hash received in 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": "your_ebanx_integration_key",
    "payment": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "address": "Nirvana society",
      "street_number": "2993",
      "street_complement": "CJ 5",
      "city": "Bangalore",
      "state": "Karnataka",
      "zipcode": "560087",
      "country": "in",
      "phone_number": "4111111111",
      "payment_type_code": "creditcard",
      "merchant_payment_code": "<{merchant_payment_code_here}>",
      "currency_code": "INR",
      "amount_total": 1000,
      "enrollment": {
        "merchant_enrollment_code": "<{merchant_enrollment_code_here}>",
        "customer_notify_hash": "<{notify_hash_received_in_PDN_api_response}>"
      }
    }
   }'

   Sample response

   A successful request returns a JSON response like this:

   {
    "payment": {
      "hash": "<{hash_here}>",
      "country": "in",
      "merchant_payment_code": "<{merchant_payment_code_here}>",
      "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": "john.doe@example.com",
        "name": "John Doe"
      }
    },
    "status": "SUCCESS"
   }

   Upon success, the payment will appear as Pending (PE) in your Merchant Area.

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

   Parameter	Requirement	Description
   integration_key	Required	Your EBANX integration key.
   mode	Required	Set to full for a complete payment request
   payment.name	Required	Customer's full name Note: Minimum 5 characters, alphabets only
   payment.email	Required	Customer's email.
   payment.phone_number	Required	Customer's phone Note: Minimum 8 digits, maximum 10 digits, numbers only
   payment.address	Required	Customer's address Note: Minimum 3 characters
   payment.street_number	Optional	Street number
   payment.street_complement	Optional	Complement information
   payment.city	Required	Customer's city Note: Minimum 3 characters, alphabets only
   payment.state	Required	Customer's state Note: Refer this for state list. Either use state code or state name
   payment.zipcode	Required	Customer's zipcode or pincode Note: Must be 6 digits, numbers only
   payment.country	Required	Set to in for India.
   payment.merchant_payment_code	Required	Unique code for the payment.
   payment.currency_code	Required	Set to INR
   payment.amount_total	Required	The total amount to be charged in INR
   payment.enrollment.merchant_enrollment_code	Required	The unique 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",
    "mode": "full",
    "payment": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "address": "AV MIRACATU",
      "street_number": "2993",
      "street_complement": "CJ 5",
      "city": "Bangalore",
      "state": "Karnataka",
      "zipcode": "560087",
      "country": "in",
      "phone_number": "4111111111",
      "payment_type_code": "creditcard",
      "instalments": "1",
      "amount_total": 1,
      "currency_code": "INR",
      "merchant_payment_code": "<{merchant_payment_code_here}>",
      "enrollment": {
        "merchant_enrollment_code": "<{merchant_enrollment_code_here}>"
      }
    }
   }'

   Sample response

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

   {
       "payment": {
           "hash": "{<hash_here>}",
           "country": "in",
           "merchant_payment_code": "<{merchant_payment_code_here}>",
           "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",
           "currency_rate": "1.0000",
           "currency_ext": "INR",
           "due_date": "2025-01-17",
           "instalments": "1",
           "payment_type_code": "creditcard",
           "transaction_status": {
               "acquirer": "EBANX",
               "code": "PENDING_AUTHENTICATION",
               "description": "Pending Authentication",
               "description_code": "PENDING_AUTHENTICATION"
           },
           "pre_approved": false,
           "capture_available": false,
           "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 Merchant Area 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

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   • Learn more about Payment Notificationschevron_right

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

   • Learn more about Retrieving Payment Statuschevron_right

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.ebanxpay.com/ws/userenrollments/query

   Sample request

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/userenrollments/query' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_ebanx_integration_key",
       "operation": "query",
       "payment_type_code": "creditcard",
       "enrollment": {
           "merchant_enrollment_code": "<{merchant_enrollment_code_here}>",
           "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' \
     --header 'Content-Type: application/json' \
     --data '{
      "integration_key": "your_ebanx_integration_key",
      "operation": "cancel",
      "payment_type_code": "creditcard",
      "enrollment": {
          "merchant_enrollment_code": "<{merchant_enrollment_code_here}>",
          "email": "john.doe@example.com",
          "country": "IN"
      }
   }'

   Sample response

   A successful cancellation will return the following JSON response:

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

10. Congratulations!

    You have successfully 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.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

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

Click to explorechevron_right

Error Codes

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

Click to explorechevron_right

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 sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.