Version: current

Card Recurring with Direct API

About this guide

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

Availability

Recurring Cards 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 cards enabled in your EBANX Dashboard.

How it works

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

  1. Enable cards recurring

    Recurring Cards 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 Cards 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 + First Charge

    Basic parameters

    ParameterDescription
    operationOperation must be request
    integration_keyYour unique and secret integration key
    payment_type_codeFor recurring card payments in India the types currently available are creditcard or debitcard

    Customer data: (Mandatory for India transactions)

    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 - 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: daily, weekly, fortnightly, monthly, bimonthly, quarterly, halfyearly, yearly and ondemand .
    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)

    Charge details

    ParameterDescription
    operationOperation must be request
    payment.namePayer full name.
    payment.emailCustomer email.
    payment.countryTwo-letter country code - 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 (Minimun 1.00 INR)
    payment.enrollment.merchant_enrollment_codeUnique identifier associated with the subscription.(character limit : 254)
    payment.enrollment.customer_notify_hashUnique identifier associated with the Pre-debit notification. This is the hash received in the response when a pre-debit notification is successfully sent.
    info

    Values shared in the following parameters on subscription object: subscription_name, expiration_date, frequency will be shared to the user via the sms sent by their issuing bank .

    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:

    {
    "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"
    }
    }
    }
    }
    note

    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 (OTP authentication) for the succeding transactions with amount under 15.000 INR. Charges above INR 15,000 will always require user authentication (2FA) for approval.

  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": "testenrollment00101",
    "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": "Sam",
    "email": "sam@xyz.com",
    "country": "in",
    "payment_type_code": "credicard",
    "merchant_payment_code": "testmandate00101",
    "currency_code": "INR",
    "amount_total": 1000,
    "enrollment": {
    "merchant_enrollment_code": "testenrollment00101",
    "customer_notify_hash": "561eb4005d491a7eb009af3f09355969b0f3ed51dda6f3bd99e50c4c41ab799e337a6cb9295cf4028a9ceccdc299850a07ecb123f0fef14bdcc6e7679633956d"
    }
    }
    }

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

    {
    "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"
    }
    info

    After receiving a successful pre debit notification to the user and meeting the mandatory wait period requirement, you can make the charge to the customer. At this point you have a pending (PE) payment in your EBANX Dashboard.

  6. Want Ebanx to handle the notifications

    If you want Ebanx to manage the predebit notification and subsequent charge without having to hit our API twice, you can simply hit us with the sample charge request and we will handle the notifications and the subsequent first charge.

    Request example:

    {
    "integration_key": ""{{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"
    }
    }
    }
    note

    Please pass us the unique merchant_enrollment_code associated with the subscription for which the charge+notify is requested.

    Successful Response:

    {
    "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"
    }
    note

    After receiving the response your payment status will be “pending” in the dashboard for 24hrs until the charge takes place.

    tip

    The recurring debit logic has to be maintained on your end , Ebanx does not control the frequency of the deductions.

    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.

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

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

    Response:

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

    Response when user paused the subscription:

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

    Response when user resumes the subscription:

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

    To see the latest status of the payment please refer to our Payment Notification document .

  9. 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": "creditcard",
    "enrollment": {
    "merchant_enrollment_code": "testenrollment00101",
    "email": "sam@xyz.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 José Cristiano de Sousa
On this page