Chargebee

Chargebee is a subscription billing platform that enables merchants to manage recurring payments across multiple gateways. By configuring EBANX as a payment gateway in Chargebee, merchants can process local credit card payments across Latin America — accepting transactions in local currencies, reducing cross-border fees, and increasing authorization rates through domestic processing.

This guide covers how to configure EBANX as a payment gateway within Chargebee, set up card settings and webhooks, and manage required fields for Latin American markets.

Features

• Local payment processing - Process credit card payments domestically in Latin American markets, increasing authorization rates and reducing cross-border transaction fees.
• Local card scheme support - Accept Visa, Mastercard, and regional card schemes such as Elo, Hipercard, CMR Falabella, Argencard, and Cencosud.
• Subscription billing - Leverage Chargebee's subscription management engine with EBANX's local acquiring for recurring charges.
• Multiple integration options - Choose from Chargebee Hosted Pages, Chargebee API, Chargebee.js, or EBANX.js depending on your PCI compliance requirements.
• Fraud management - Use EBANX Device Fingerprint for fraud detection on payments processed through Chargebee.
• Webhook notifications - Receive refund and chargeback status updates through manually configured webhooks.

How it works

1. 1 Add EBANX as a payment gateway in your Chargebee site using your EBANX Integration Key and Public Integration Key.

2. 2 Configure card settings, 3D Secure, and webhook notifications.

3. 3 Customers complete checkout through your chosen integration method (Hosted Pages, API, or Chargebee.js).

4. 4 Chargebee routes the payment to EBANX for local processing and manages the subscription lifecycle.

Requirements

Before starting the integration, ensure you have the following:

• Chargebee account - An active Chargebee site. If you don't have one, sign up at Chargebee.
• EBANX API credentials - Your Integration Key and Public Integration Key. If you don't have them, complete the Merchant Signup Form.

Supported payment methods

Payment Method	Regions	Currencies	Description
Credit Cards (Visa, Mastercard)	Argentina, Bolivia, Brazil, Chile, Colombia, Costa Rica, Dominican Republic, Ecuador, El Salvador, Guatemala, Mexico, Panama, Paraguay, Peru, Uruguay	ARS, BOB, BRL, CLP, COP, CRC, DOP, USD, GTQ, MXN, PAB, PYG, PEN, UYU	Global card schemes processed locally through EBANX
Elo	Brazil	BRL	Brazilian local card scheme
Hipercard	Brazil	BRL	Brazilian local card scheme
CMR Falabella	Chile, Colombia, Peru	CLP, COP, PEN	Regional card scheme across Andean countries
Argencard	Argentina	ARS	Argentine local card scheme
Cencosud	Argentina, Chile	ARS, CLP	Regional card scheme

Info

This integration supports credit cards only. Debit cards and alternative payment methods (Pix, Boleto, OXXO) are not supported. For alternative payment methods, use the EBANX Direct API or another channel partner.

Key details

Feature	Details
Integration type	Dashboard-configured
Supported operations	Purchase, Refund, Chargeback notifications
3D Secure	Supported for credit cards issued in Mexico only
Card on File	Supported via Chargebee's stored credential parameters (CIT/MIT)
Stored credentials	CIT sends provided in card_cvv_mode; MIT sends recurrent
Account Updater	Not supported
Statement Descriptor	Not supported (EBANX does not allow dynamic descriptors)
EBANX credentials needed	Integration Key and Public Integration Key

Configuration steps

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

1. Retrieve your EBANX credentials

   Log in to your EBANX Dashboard at dashboard.ebanx.com and navigate to your account settings.

   Open the Integration tab. Click on your profile name to expand the drop-down menu, then click Account Settings. Select the Integration tab on the Settings page.

   Copy your keys. Under the Test Integration Keys section, copy both the Integration Key and the Public Integration Key. Save these values — you will need them in the next step.

   Info

   Start with your Test Integration Keys for sandbox testing. When you are ready to go live, switch to your Live Integration Keys from the same settings page.

2. Add EBANX as a gateway in Chargebee

   Log in to your Chargebee site at app.chargebee.com.

   Navigate to gateway settings. Go to Settings > Configure Chargebee > Payment Gateways.

   Add the EBANX gateway. Click the Add Gateway button in the top right corner and select EBANX from the list of gateways.

   Enter your credentials. Paste your Integration Key and Public Integration Key into the dedicated fields.

   Select the Merchant Country. Choose the country where the payment is being processed. For example, if processing payments in Brazil, set the Merchant Country to Brazil. If processing in Mexico, set it to Mexico.

   Connect the gateway. Click Connect. EBANX will be added to your account if the credentials are valid.

3. Configure card settings

   After connecting the gateway, click Manage to open the Configure EBANX page and adjust the following settings:

   Card Verification. Enable this option to allow card verification when a customer adds a new card.

   Card retention. The option Always retain card information in EBANX when customer updates it determines where updated cards are vaulted for existing customers when using multiple gateways. Enable to retain cards in EBANX even if smart routing changes to a new gateway. Disable to gradually migrate customers to the new gateway as they update their cards.

   3D Secure. Enable Enable 3D Secure to activate authentication for card payments. This currently applies only to credit cards issued in Mexico.

   Click Save and then Apply on the Configure EBANX page.

4. Choose your integration option

   Chargebee offers multiple ways to collect payment information from your customers. Select the one that best fits your PCI compliance requirements:

   Integration Method	Description	PCI Requirements
   Chargebee Hosted Pages	Card information is collected by Chargebee's checkout and passed directly to EBANX. HPv3 is supported.	Low
   Chargebee API + EBANX	You collect card information and pass it to Chargebee via the API, which routes it to EBANX.	High
   Chargebee.js (Components and Fields)	Card information is collected by Chargebee's components and fields, then tokenized with EBANX.	Low
   EBANX.js + Chargebee API	Collect card details using EBANX's hosted fields and tokenize using Chargebee.js.	Low

5. Congratulations!

   You have successfully configured EBANX as a payment gateway in Chargebee. Your customers can now pay with local credit cards across Latin America through your Chargebee subscription checkout.

Webhook configuration

Danger

Webhooks are mandatory for receiving refund and chargeback notifications from EBANX. Without proper webhook configuration, status updates will not be delivered to Chargebee.

1. Copy the Notification URL from Chargebee

   In your Chargebee site, navigate to the Configure EBANX page. Copy the Notification URL displayed on this page.

2. Paste the URL in your EBANX Dashboard

   Open your EBANX Dashboard at dashboard.ebanx.com. Click your profile name, then Account Settings, and select the Integration tab.

   Configure the notification URL. Paste the Notification URL copied from Chargebee into the Test Status Change Notification URL field under the Test Service URLs section.

   Save the settings. Click Save Integration Settings.

   Caution

   When going live, repeat this process using the Live Status Change Notification URL field under the Live Service URLs section.

Limitations

General limitations

• Credit cards only — This integration does not support debit cards or alternative payment methods (Pix, Boleto, OXXO, etc.).
• 3D Secure — 3DS authentication is supported exclusively for credit cards issued in Mexico.
• Account Updater — Not supported in this integration.
• Statement Descriptor — EBANX does not support dynamic statement/transaction descriptors.
• Chargeback notifications — EBANX notifies only when a chargeback is initiated (not when it is resolved).

Country-specific requirements

• Document ID is mandatory for payment processing in Argentina, Brazil, and Uruguay. See the Required Fields section below.
• Billing address and customer name must be collected for all transactions.
• Customer email is mandatory for all transactions.

Required fields

Document ID

A Document ID is a unique number used to verify an individual's identity. Its format varies by country.

Country	Document Types
Argentina	CDI, CUIL
Brazil	CPF, CNPJ
Uruguay	CI

Collection methods:

• Chargebee Hosted Pages — The Document ID field is automatically added to the checkout form when EBANX is configured as the gateway. Chargebee validates the format using EBANX.js.
• Chargebee.js — You must incorporate Document ID collection into your checkout and validate it before sending it through the Chargebee API.
• Chargebee API — Include the document parameter via Payment Sources > additional_information > Ebanx > payer > document. Validate this field on your frontend.

Billing address

Billing address fields (address1, city, state, zip, country) and customer name (first_name, last_name) are mandatory. To enable these in Chargebee Hosted Pages:

1. Go to Settings > Configure Chargebee > Checkout and Self-Serve Portal.
2. Switch to the Fields tab and select Payments.
3. Enable all address fields and make them mandatory, including first and last name.
4. Click Publish.

Testing

Sandbox configuration

1. Use your Test Integration Keys from the EBANX Dashboard when configuring the gateway in Chargebee.
2. Configure the Test Status Change Notification URL for webhook testing.
3. Use EBANX test credit cards and test customer data to simulate transactions.

Validation checklist

• Verify that the EBANX gateway connects successfully in Chargebee.
• Process a test payment through your chosen integration method.
• Confirm that webhook notifications are received for refund and chargeback events.
• Test with Document IDs for countries where it is mandatory.
• Verify 3DS flow with a Mexican-issued test card (if applicable).

Going live

Before switching to production, complete the following:

• Replace Test Integration Keys with Live Integration Keys in Chargebee's gateway configuration.
• Update the webhook notification URL from the Test field to the Live Status Change Notification URL in the EBANX Dashboard.
• Verify that smart routing rules in Chargebee are configured correctly for the target countries.
• Confirm that billing address fields and Document ID collection are enabled and mandatory in your checkout flow.
• Run a live transaction with a small amount to validate end-to-end processing.

Troubleshooting

Gateway connection fails when adding EBANX in Chargebee

Verify that you are using the correct Integration Key and Public Integration Key. Ensure you are using the Test keys for sandbox and Live keys for production. Keys are available under Account Settings > Integration in the EBANX Dashboard.

Payments are declined due to missing Document ID

Document ID is mandatory in Argentina, Brazil, and Uruguay. Ensure your checkout collects this field. When using Hosted Pages, the field appears automatically. When using the API, pass it via additional_information > Ebanx > payer > document.

3D Secure is not triggered during checkout

3DS is only supported for credit cards issued in Mexico. Ensure the Enable 3D Secure option is enabled in the Configure EBANX page in Chargebee.

Webhook notifications are not received

Confirm that the Notification URL from Chargebee was pasted into the correct field in the EBANX Dashboard (Test Status Change Notification URL for sandbox, Live Status Change Notification URL for production). Click Save Integration Settings after pasting.

Billing address validation errors

Ensure all mandatory address fields are enabled in Chargebee's checkout configuration: Settings > Configure Chargebee > Checkout and Self-Serve Portal > Fields > Payments.

Fraud management

EBANX Device Fingerprint can be used as the Device ID for fraud detection on payments processed through Chargebee. This feature is supported when using Chargebee.js or Chargebee Hosted Pages.

Migration

When migrating into Chargebee with existing EBANX tokens or moving cards from a different gateway to EBANX, ensure the following are sent along with the permanent token:

• Document ID (mandatory in most Latin American markets)
• Billing Address

These must be sent as Additional Info. Refer to Chargebee's Migration documentation for details on the migration process.

Resources

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.