Zuora

Zuora is a subscription management and billing platform that enables merchants to handle recurring billing, revenue recognition, and subscription analytics. By integrating EBANX with Zuora, merchants can process credit card payments, Pix, Pix Automatico, and UPI transactions across Latin America, Africa, and India directly from the Zuora dashboard.

This guide covers how to configure EBANX as a payment gateway within Zuora, the supported payment methods and countries, testing procedures, and troubleshooting.

Features

• Subscription billing - Process recurring payments for subscriptions across Latin America, Africa, and India through EBANX.
• Multiple payment methods - Accept credit cards, Pix, Pix Automatico, and UPI through a single gateway integration.
• 3D Secure 2.0 - Protect credit card transactions with 3DS authentication.
• Delayed capture - Pre-authorize credit card payments and capture them later.
• Stored credentials - Securely store and reuse payment methods for recurring billing.
• Refunds - Issue referenced refunds directly from Zuora.

Requirements

Before starting the integration, ensure you have the following:

• Zuora account - An active Zuora tenant with access to payment gateway configuration. If not, visit Zuora.
• EBANX API credentials - Your EBANX Integration Key and Public Integration Key, available in the EBANX Dashboard. If you don't have an account, complete the Merchant Signup Form.
• EBANX gateway enabled - The EBANX payment gateway integration must be enabled for your Zuora tenant. Contact Zuora support to enable it if needed.

How it works

1. 1 Configure EBANX as a payment gateway in your Zuora tenant settings using your EBANX credentials.

2. 2 Create subscriptions and associate payment methods (credit card, Pix, Pix Automatico, UPI) to customer accounts.

3. 3 Zuora routes payment transactions to EBANX for processing.

4. 4 EBANX processes the payment with the local acquirer or payment network and returns the result to Zuora.

5. 5 Zuora updates the invoice and subscription status based on the payment outcome.

Supported payment methods

Payment Method	Countries	Currencies	Description
Credit Card	Brazil	BRL, USD	Visa, Mastercard, Amex, Diners Club, Elo, and Hipercard. Includes local Brazilian card brands.
Credit Card	Argentina, Chile, Colombia, Mexico, Peru, Uruguay	ARS, CLP, COP, MXN, PEN, UYU, USD	Visa, Mastercard, Amex, and Diners Club. Standard processing with 3DS 2.0 support.
Credit Card	Costa Rica, Dominican Republic, El Salvador, Guatemala, Nigeria, Panama, Paraguay, South Africa	USD	Visa and Mastercard only.
Pix	Brazil	BRL	Instant bank transfer via Pix QR code.
Pix Automatico	Brazil	BRL	Recurring Pix payments for subscriptions.
UPI	India	INR	Unified Payments Interface for Indian transactions.

Key details

Feature	Details
Integration type	Dashboard-configured (via Zuora tenant settings)
Supported operations	Validate (zero and non-zero amounts), Payment, Payment cancel, Referenced refund
3D Secure 2.0	Yes (credit card only)
Delayed capture	Yes (credit card only)
Stored credential transactions	Yes (credit card only)
Real-time reconciliation	Yes
Level 2 / Level 3 card data	No
Payment Method Updater	No
Gateway reconciliation	No

Instructions

Follow the steps below to configure EBANX as a payment gateway in Zuora.

1. Enable the EBANX gateway integration

   Before configuring an EBANX gateway instance, the EBANX payment gateway integration must be enabled for your Zuora tenant. If it is not already enabled, contact Zuora support or refer to Zuora's documentation on enabling payment gateway integrations.

   You will also need your EBANX merchant account enabled for the target payment methods (credit cards, Pix, Pix Automatico, UPI) and access to the EBANX Dashboard to retrieve your credentials.

2. Navigate to gateway configuration

   Log in to your Zuora tenant. Click your username in the upper right corner and navigate to Settings > Payments > Setup Payment Gateway.

   Open the configuration tab. On the Payment Gateways page, click the Configure Gateway Instance tab and scroll to the bottom.

   Select EBANX. On the Configure Gateway Instance tab, select EBANX from the Gateway Type drop-down list.

3. Configure basic information

   Enter a gateway name. In the Name field, enter a descriptive name for the gateway instance (e.g., EBANX Production or EBANX Sandbox).

   Enable test mode (optional). If you are setting up a sandbox environment, enable the Use Gateway test Environment checkbox. This routes transactions to the EBANX sandbox endpoint instead of production.

4. Enter EBANX credentials

   Integration Key. In the Integration Key field, enter your EBANX Integration Key. You can find this in the EBANX Dashboard under your account settings.

   Public Integration Key. In the Public Integration Key field, enter your EBANX Public Integration Key, also available in the EBANX Dashboard.

   Info

   Log in to the EBANX Dashboard and navigate to your integration settings. You will find both the Integration Key and Public Integration Key there. Use sandbox keys when the test environment checkbox is enabled, and production keys for live transactions.

5. Configure additional metadata (optional)

   You can define custom metadata fields that will be included in gateway requests. This metadata is added to the request body and passed to EBANX, which can be used for analysis, reporting, or building custom fraud protection rules.

   Supported transaction types for metadata:

   • Payment object - Credit Card, CC Reference Transaction, Bank Transfer, ACH, Apple Pay, Google Pay.
   • Payment Method object (validation) - Credit Card, CC Reference Transaction, Apple Pay, Google Pay.
   • Authorization - Credit Card, Google Pay.

   To add metadata: Click Add New Metadata in the Additional Metadata section. Enter a unique metadata field name using only alphanumeric characters and underscores. You can define up to 20 metadata fields.

6. Save and verify

   Click Save Gateway Information to complete the configuration. After saving, verify the gateway instance appears in your list of configured gateways and is set as active.

Testing

To test the integration in a sandbox environment:

1. Enable test mode - When configuring the EBANX gateway instance, enable the Use Gateway test Environment checkbox. This routes all transactions to the EBANX sandbox endpoint (sandbox.ebanx.com) instead of the production endpoint (api.ebanxpay.com).
2. Use sandbox credentials - Enter your EBANX sandbox Integration Key and Public Integration Key. These are different from your production credentials and can be obtained from the EBANX Dashboard sandbox environment.
3. Process test transactions - Create test subscriptions and payments in Zuora using the sandbox gateway. Verify that payments are processed correctly by checking the transaction status in both Zuora and the EBANX Dashboard. For credit card testing, refer to the EBANX test card numbers documentation.

Going live

Before switching to production, verify the following:

• All test transactions completed successfully in the sandbox environment.
• Production EBANX credentials (Integration Key and Public Integration Key) are ready.
• The Use Gateway test Environment checkbox is disabled on the production gateway instance.
• Card brands configured in Zuora match those enabled in your EBANX merchant account.
• Refund workflows include the required description in the comment field.
• Payment notification callbacks are configured in the EBANX Dashboard if needed.

Troubleshooting

If you encounter issues during setup or transaction processing, check the following common scenarios. For a complete list of supported features and known limitations, refer to the Zuora EBANX gateway documentation.

Gateway not appearing in the Gateway Type drop-down

The EBANX payment gateway integration may not be enabled for your Zuora tenant. Contact Zuora support to request activation.

Transactions routing to the wrong environment

Verify the Use Gateway test Environment checkbox is set correctly. Enabled routes to sandbox; disabled routes to production. Also ensure you are using the correct set of credentials (sandbox vs. production) for the selected environment.

Refund fails

EBANX requires a description for all refund requests. When refunding through Zuora's API or UI, ensure the comment field contains the refund reason. This field maps to EBANX's description parameter.

Resources

For additional reference, consult the following resources:

• Zuora EBANX Gateway Integration Documentation
• Zuora Supported Features for EBANX
• Zuora Supported Payment Methods for EBANX
• Zuora Field Mappings for EBANX

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.