Recurly

Recurly is a subscription management platform that enables merchants to handle recurring billing across multiple payment gateways. By integrating EBANX with Recurly, merchants can accept local payment methods in APAC and Latin American markets — including UPI AutoPay (India), Pix Automatico (Brazil), and MercadoPago Connect — directly through Recurly's billing engine.

This guide covers how to configure EBANX as a payment gateway within Recurly, set up supported payment methods, configure webhooks, and manage subscriptions.

Features

• Subscription management - Use Recurly's robust subscription billing platform with EBANX's local payment methods in emerging markets.
• Alternative payment methods - Accept payments via UPI AutoPay (India), Pix Automatico (Brazil), and MercadoPago Connect (Brazil, Mexico, Chile, Uruguay, Argentina).
• Recurring transactions - Manage enrollment-based recurring payments, retries, and refunds through Recurly's billing engine.
• Currencies - Process transactions in INR, BRL, ARS, CLP, MXN, and UYU.

How it works

1. 1 Add EBANX as a payment gateway within your Recurly account using your EBANX Integration Key.

2. 2 Enable the desired payment methods (UPI AutoPay, Pix Automatico, MercadoPago Connect) and currencies.

3. 3 Configure webhooks in EBANX to send enrollment and payment status updates to Recurly.

4. 4 Customers subscribe and authorize mandates through their banking or wallet apps.

Requirements

Before starting the integration, ensure you have the following:

• Recurly Account - An active Recurly account on any subscription plan. If not, sign up at Recurly.
• EBANX API Credentials - Ensure you have your EBANX Integration Key. If not, complete the Merchant Signup Form.

Supported payment methods

Payment Method	Regions	Currencies	Description
UPI AutoPay	India	INR	Recurring mandate-based payments via UPI apps
Pix Automatico	Brazil	BRL	Recurring Pix-based automatic payments
MercadoPago Connect	Brazil, Mexico, Chile, Uruguay, Argentina	BRL, MXN, CLP, UYU, ARS	Digital wallet payments via MercadoPago Connect

Key details

Feature	Description
Services that work with Recurly	Payment Processing, Subscriptions, Automatic Subscription Cancellation
Supported Operations	Subscription Mandate Enrollment, Recurring Transactions, Refunds
Gateway Specific 3DS2 Supported	No
Card On File Supported	No

Configuring EBANX in Recurly

Follow the steps below to set up EBANX as a payment gateway in Recurly.

1. Obtain EBANX credentials

   Log in to your EBANX Dashboard. You will need an active relationship with EBANX. Switch to Production mode for production keys or Sandbox mode for sandbox keys.

   Go to Account Settings — click your name in the top-right corner and choose Account Settings. Select the Integration tab and copy your Integration Key.

   Warning

   Only the Integration Key will work with Recurly. The Public Integration Key will not function.

2. Enter credentials in Recurly

   Log in to your Recurly account and go to Configuration > Payment Gateways. Click Add a New Gateway at the top-right, choose Ebanx from the list, and paste your Integration Key into the "Integration Key" field.

3. Set your payment methods

   Under Accepted Card Types, you won't see any card options since this gateway currently supports regional alternative payment methods (APMs).

   Enable the payment methods you want under Alternative Payment Methods:

   • UPI AutoPay - For recurring payments in India (INR only).
   • Pix Automatico - For recurring payments in Brazil (BRL only).
   • MercadoPago Connect - For payments in Brazil, Mexico, Chile, Uruguay, and Argentina (BRL, MXN, CLP, UYU, ARS).

4. Enable currencies

   Ensure you are enabling the correct currencies per payment method:

   • UPI AutoPay: INR only
   • Pix Automatico: BRL only
   • MercadoPago Connect: BRL, ARS, CLP, MXN, or UYU

5. Save and enable the gateway

   Click Add Payment Gateway at the bottom. You'll see Ebanx added to your list of Production Gateways in Recurly with a status of Enabled.

Configuring webhooks in EBANX

Danger

Webhooks are essential for enrollment and payment status updates. Without proper webhook configuration, enrollment, mandate status, and payment updates will not occur properly.

1. Set Recurly callback endpoint in EBANX

   Log into your EBANX Dashboard, click on your user in the top right, and choose Account Settings.

   Select the Integration tab and enter your site callback URL in the Status change notification URL field. The format is https://callbacks.recurly.com/ebanx/{{subdomain}} — replace {{subdomain}} with your Recurly site subdomain. Then click Save integration settings at the bottom of the page.

   Caution

   The state of your EBANX dashboard (sandbox or production) determines which Service URLs are updated. Ensure your service URL points at the correct Recurly site: EBANX sandbox URLs should point at Recurly sandbox sites, and production URLs at production sites.

Limitations

General limitations

• Ad-hoc or one-time customer-initiated purchases and merchant-initiated force collections are not supported.
• Recurly.js is not supported with UPI AutoPay or Pix Automatico. Use the Recurly API to facilitate requests.
• Refunds through EBANX must be the full amount.
• Chargebacks are not reflected or supported at this time.
• Transaction types of Authorize and Capture, and Void are not supported. EBANX transactions must be refunded.
• Subscription upgrades may cause declines because mandates stored on the consumer's bank app control the amount and frequency.
• Trials without payment data (payment data on file) are not supported.
• One-time transactions are not supported as these payment methods support renewals only.
• Multiple subscriptions on a single account are not supported. Each individual subscription uses a mandate ID, and only one mandate ID is allowed per account.

UPI / India specific limitations

• Customer mandates cannot be migrated to Recurly if they exist on another platform. Customers must cancel those mandates and resubscribe per RBI and NPCI rules.
• RBI mandates limit individual transactions to 15,000 INR without going through a consumer two-factor flow.
• Billing Info updates are not supported with UPI AutoPay. If customers need to update their VPA or bank accounts, they must cancel their existing mandate/subscription and re-subscribe.

Pix Automatico specific limitations

• Pix Automatico transactions have a waiting period between consumer authentication and the start date for the first renewal transaction. Avoid forced or early conversions for trial subscriptions on Pix.

Required fields

UPI AutoPay

Field	Description
VPA	Virtual Payment Address
Email address	Customer email address
First and last name	Customer first and last name
Billing address	Street address, city, region/state, country, postal code / PIN code
Phone number	Customer phone number

Pix Automatico and MercadoPago Connect

Field	Description
Name	Customer name
Billing address	Customer billing address
Email address	Customer email address
Phone number	Customer phone number
Tax ID / Tax ID type	Required when the region requires it (Brazil)

Subscription behavior

Retries and dunning

Retries are supported on UPI AutoPay, Pix Automatico, and MercadoPago Connect when your dunning settings are not set to expire subscriptions immediately. Ensure your dunning settings are loosened to avoid immediately expiring subscriptions, so that retries can function properly.

Transaction, invoice, and subscription status

When processing with UPI AutoPay and Pix Automatico, as with any asynchronous payment method in Recurly, subscriptions are immediately active, but transactions and invoices will be in a scheduled/processing state until the pre-renewal notification receives an update and the payment is triggered. If customers do not authorize a subscription enrollment or payment via their respective banking app, transactions will fail and subscriptions will be expired upon consumer rejection.

Testing

Perform a test transaction to confirm the integration works. It is recommended to test in development mode on your Recurly sandbox site before going live.

1. Ensure your Sandbox credentials are entered in Recurly and your EBANX account is in Sandbox mode.
2. Create a test subscription using one of the supported payment methods.
3. Verify that enrollment and payment webhooks are received correctly.

Going live

1. Once testing is successful, you're ready to accept live payments through EBANX.
2. Make sure your Production Credentials are entered in Recurly and your EBANX account is in Production mode.
3. Make sure you have EBANX production webhooks enabled prior to launch.

Troubleshooting

My UPI subscription is failing. How can I fix this?

• Confirm the subscription price hasn't changed without re-engaging the customer.
• Make sure the customer is responding to UPI app push notifications, especially for charges above 15,000 INR.

I updated my customer's VPA, but the original account was charged. How do I fix this?

Billing Info Updates made through Recurly APIs aren't supported with UPI AutoPay. If a customer has a new VPA, they must re-enroll in the subscription:

• Cancel the current subscription and have your customer re-subscribe using their new VPA.
• If customers only need to update their bank details, they can do so in the UPI App directly.

A subscription renewal failed, and I cannot attempt collection. Why?

Merchant-initiated one-time transactions such as one-time invoices and force collections aren't supported with UPI AutoPay. Reach out to your customer about payment options.

I converted a Pix trial early and it declined. Why?

Pix Automatico transactions have a waiting period between consumer authentication and the start date you can charge the first renewal transaction. It is best to avoid forced or early conversions for trial subscriptions on Pix.

Resources

For more details on the Recurly + EBANX integration, refer to Recurly's EBANX Gateway documentation.

Use the following resources when testing in your sandbox environment.

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right

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.