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. In Brazil, merchants can also accept one-time Pix payments and recurring Pix Automático payments in BRL.

This guide covers how to configure EBANX as a payment gateway within Chargebee, set up card settings and webhooks, enable Pix and Pix Automático, 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.
• Pix and Pix Automático - Accept one-time Pix payments and recurring Pix Automático payments in BRL for customers in Brazil.
• Subscription billing - Use 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 Pix payment status, refund, and chargeback updates through manually configured webhooks.

How it works

Card payments

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.

Pix payments

Pix is a push-based, asynchronous payment method. After the customer submits checkout, Chargebee creates the payment with EBANX, which returns the Pix code in qr_code_value. Chargebee renders the QR code directly in the checkout instead of redirecting the customer. The transaction stays pending until the customer pays in their bank app and EBANX sends a status change notification to Chargebee.

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.
• Pix enablement (optional) - To accept Pix, your EBANX merchant account must have Pix enabled (and Pix Automático for recurring payments), and Chargebee Support must enable Pix Payments via EBANX on your Chargebee live and test sites.

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
Pix	Brazil	BRL	One-time instant payment through QR code or payment link
Pix Automático	Brazil	BRL	Recurring Pix payments authorized through a mandate

Info

Debit cards and other alternative payment methods (such as Boleto and OXXO) are not supported in this integration. For these payment methods, use the EBANX Direct API or another channel partner.

Warning

Pix Payments via EBANX is a Private Beta release in Chargebee. Contact Chargebee Support to enable it on your live and test sites.

Key details

Feature	Details
Integration type	Dashboard-configured
Supported operations	Purchase, Refund, Chargeback notifications
Pix integration mode	Asynchronous only (webhooks mandatory)
Pix capture	Auto capture
Pix Automático	Supported (mandate created with the first payment)
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.	Low
   Chargebee API + EBANX	You collect card information and pass it to Chargebee via the API, which routes it to EBANX.	High
   Chargebee.js (Raw card details)	You collect raw card details in your custom checkout and pass them to the Chargebee.js 3DS Helper to run the 3DS flow.	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. To also accept Pix in Brazil, follow the Pix and Pix Automático section.

Webhook configuration

Danger

Webhooks are mandatory for receiving refund and chargeback notifications from EBANX, and for confirming Pix payments. 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.

Pix and Pix Automático

Pix is a Brazilian instant payment method that lets customers pay by scanning a QR code or opening a payment link in their bank app. Chargebee supports two Pix flows through EBANX:

• Pix (one-time) - A single instant payment, typically used for one-time charges or one-off invoices.
• Pix Automático (recurring) - A recurring authorization (mandate) that lets Chargebee debit the customer for future subscription renewals without a new QR code each cycle. See Pix Automático.

Pix applies only to payments in BRL for customers in Brazil.

Pix integration options

Integration Method	Description
Chargebee Hosted Pages (in-app checkout)	Accept Pix payments using Chargebee's in-app hosted checkout with minimal integration effort.
Chargebee Hosted Pages (full-page checkout)	Accept Pix payments using Chargebee's full-page hosted checkout.
Chargebee.js	Collect Pix payer details (name, email, and Document ID) in your custom checkout using Chargebee.js.
Chargebee API	Process Pix payments using Chargebee APIs for a fully custom checkout and payment flow.

Pix prerequisites

• EBANX is configured as a gateway in your Chargebee site (see Configuration steps).
• Your EBANX merchant account has Pix enabled, and Pix Automático if you need recurring payments.
• Pix Payments via EBANX is enabled on your Chargebee site by Chargebee Support.
• The Merchant Country is set to Brazil and you transact in BRL.
• Your checkout collects the customer name, email, Document ID (CPF or CNPJ), and billing address. See Required fields.

1. Enable Pix in the EBANX gateway

   Open the EBANX gateway. In the Chargebee app, go to Settings > Configure Chargebee > Payment Gateways and open your EBANX gateway.

   Turn on Pix. On the Configure EBANX page, turn on Pix under Payment methods.

   Configure the Notification URL. Copy the Notification URL from the Configure EBANX page. In your EBANX Dashboard, go to Account Settings > Integration, paste it into the Test Status Change Notification URL field under Test Service URLs for sandbox, or the Live Status Change Notification URL field under Live Service URLs for production, and click Save Integration Settings. See Webhook configuration.

   Save the configuration. Click Save and then Apply on the Configure EBANX page.

   Danger

   Webhooks are mandatory for Pix. Chargebee processes Pix payments asynchronously and relies on the EBANX status change notification to confirm whether a payment succeeded or failed.

2. Configure Smart Routing for Pix

   Open Smart Routing. On the Payment Gateways page under Settings > Configure Chargebee, click Manage rules under Smart Routing.

   Add EBANX for BRL. Go to the Pix section and click Add a gateway for BRL.

   Select the gateway. From the Choose a payment gateway dropdown, select the EBANX gateway instance that has Pix enabled, then click Save.

   Note

   Smart Routing changes affect only new payment methods added by your customers. Existing payment methods remain linked to their current gateway.

Pix Automático mandate

For recurring subscriptions, Chargebee uses Pix Automático, which creates a mandate (enrollment) together with the first payment. The mandate authorizes Chargebee to collect future recurring charges without a new QR code each cycle.

• Maximum amount floor - The mandate carries a max_amount_floor, the lowest value the customer can set as the maximum amount for recurring charges in their bank app. You can set the max_amount_floor for your merchant account in Chargebee. When it is not set, Chargebee derives it from the upcoming renewal amount (the next invoice estimate, or the plan amount when no estimate is available) plus a 10% buffer to absorb minor changes such as taxes or proration. The customer can set or later update a higher limit, and neither the merchant nor EBANX has visibility into the value chosen. A charge above the customer's limit is rejected with MAX_AMOUNT_EXCEEDED. See Pix Automático error scenarios.
• Billing cycle - The mandate carries a fixed billing frequency and start date. Pix Automático allows only one charge per billing cycle that reaches a processing attempt (confirmed, or failed after liquidation was attempted). If a scheduled charge is canceled before liquidation, for example with TIMEOUT or MAX_AMOUNT_EXCEEDED, a new charge can be scheduled in the same cycle. See Scheduling a new payment vs. retrying an existing one.
• Scheduling - Chargebee schedules each recurring charge 2 to 10 days before its due_date, as required by Pix Automático rules. The charge stays pending until it settles on the due_date. See Pix Automático recurring payments.
• Retries - A failed recurring charge can be retried up to three times within seven days, with at most one retry per day. See Pix Automático payment retries.
• Subscription name - Chargebee sends the merchant's statement descriptor as the subscription_name of the mandate (maximum 35 characters), which is displayed in the customer's bank app.
• Transaction initiation - The first Pix payment is customer-initiated (CIT) at checkout. Subsequent Pix Automático charges are merchant-initiated (MIT).

Caution

For trial subscriptions, Chargebee bases max_amount_floor on the amount charged when the trial ends, not the zero trial amount.

Pix payment features

Feature	Supported	Behavior
Integration sync mode	Yes (asynchronous only)	Chargebee receives the final payment status through the EBANX status change notification.
Capture	Yes (auto capture)	Pix is push-based and always auto-captured once the customer pays. No configuration required.
Recurring payments (Pix Automático)	Yes	Mandate created at the first payment with max_amount_floor (minimum for the customer-defined limit), set by the merchant in Chargebee or derived from the renewal amount plus a 10% buffer. Fixed billing cycles with one processed charge per cycle, scheduled 2 to 10 days before the due_date.
Retries (Pix Automático)	Yes	Up to three retries within seven days, with at most one retry per day.
Document ID collection	Yes	Collected automatically in Hosted Pages when EBANX is selected through Smart Routing. For Chargebee.js or API, collect and pass it yourself.
Statement descriptor	Pix Automático only	The merchant's statement descriptor is sent as the mandate subscription_name (maximum 35 characters) and displayed in the customer's bank app. Dynamic statement descriptors are not supported.
Chargeback management	No	Automated chargeback management is not supported for Pix. Refunds and returns are communicated through the EBANX status change notification.
Fraud management	Yes	EBANX Device Fingerprint is supported as the Device ID.
Error intelligence	Yes	Standardized categorization of payment failures. No configuration required.
Gateway transaction details	Yes	Raw gateway responses are available on the Chargebee transaction page under Error details.

Reconciliation

For financial reconciliation between Chargebee and EBANX, use the Chargebee transaction field id_at_gateway, which maps to the EBANX payment hash. Retrieve the value from the Chargebee transaction details and locate the matching payment in the EBANX Dashboard.

Checkout flow

The following flows describe the customer experience in Chargebee Hosted Pages with EBANX as the gateway. Document fields appear only when EBANX is selected through Smart Routing.

Card checkout

1. Review the plan details and click Proceed to Checkout.
2. Enter the email address and click Next.
3. Enter the account details and click Next.
4. Enter the billing address and click Next.
5. Select Credit Card as the payment method.
6. Enter the card details, select the document type, enter the document number, and click Next.
7. On the Complete Your Order page, review the plan and payment details and click Pay and Subscribe. Chargebee then creates the subscription.

Pix checkout

1. Review the order details on the Your order page and click Proceed To Checkout.
2. Enter the email address and click Next.
3. Enter the billing address and click Next.
4. On the Add your payment details page, select Pix as the payment method.
5. Enter the payer details, select the Document type (for example, Brazil - CPF), enter the Document number, and click Next.
6. Review the order summary on the Complete your order page and click Pay & subscribe.
7. Complete the payment by scanning the QR code displayed in the checkout with the bank app, or by copying the Pix code into the bank app.

Limitations

General limitations

• Supported payment methods — This integration supports credit cards and, in Brazil, Pix and Pix Automático. Debit cards and other alternative payment methods (Boleto, OXXO, etc.) are not supported.
• Pix availability — Pix is a Private Beta release in Chargebee, available only for BRL payments in Brazil, and must be enabled by Chargebee Support.
• 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. For Pix Automático, the mandate subscription_name (maximum 35 characters) is displayed in the customer's bank app.
• Pix Automático billing cycles — Pix Automático supports fixed billing cycles with only one charge per cycle that reaches a processing attempt. Charges canceled before liquidation do not use up the cycle.
• Chargeback notifications — EBANX notifies only when a chargeback is initiated (not when it is resolved). Automated chargeback management is not supported for Pix.

Country-specific requirements

• Document ID is mandatory for payment processing in Argentina, Brazil, Chile, Ecuador, Mexico, Peru, 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. The Document ID is required for payment processing in Argentina, Brazil, Chile, Ecuador, Mexico, Peru, and Uruguay.

Examples of document types:

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. Address fields appear only if None is selected in the In checkout, prefill address information from drop-down menu.
5. Optionally, choose to prefill address information from Billing or Shipping details using the same drop-down menu.

Customer email

Customer email is mandatory for all EBANX transactions processed through Chargebee.

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

Testing Pix

1. Ensure Pix is turned on in the EBANX gateway on your Chargebee test site and that Smart Routing sends BRL Pix payments to EBANX.
2. Ensure the Notification URL is configured in your EBANX Dashboard.
3. Complete a Pix checkout using EBANX sandbox test data, confirm the payment in the EBANX sandbox, and verify that the transaction status updates in Chargebee. For Pix Automático scenarios, see the Pix Automático Sandbox Simulator.

Note

Because Pix is asynchronous, the transaction remains pending until the payment is confirmed in the sandbox and EBANX sends the status change notification to Chargebee.

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.
• For Pix, confirm the live Notification URL is configured and run end-to-end tests with a real Brazilian bank account and CPF/CNPJ, including a recurring Pix Automático renewal.

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, Chile, Ecuador, Mexico, Peru, 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.

Pix payments remain pending

Pix is asynchronous. Confirm that the Notification URL is configured in the EBANX Dashboard so Chargebee receives the status change notification. In sandbox, the payment stays pending until you confirm it.

Pix is not offered at checkout

Confirm that Pix is turned on in the Configure EBANX page, that Smart Routing has the EBANX gateway assigned for BRL in the Pix section, that the Merchant Country is Brazil, and that Chargebee Support has enabled Pix Payments via EBANX on your site.

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, and applies to both card and Pix payments.

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.