Pix Payments via EBANX
This feature is a Private Beta release. Contact Chargebee Support to enable Pix Payments via EBANX for your live and test sites.
Pix is a Brazilian instant payment method that lets customers pay by scanning a QR code or opening a payment link with their bank app. Chargebee lets you configure Pix payments using EBANX. Pix applies only to payments made in BRL for customers in Brazil.
Chargebee supports two Pix flows via EBANX:
- Pix (one-time): A single instant payment, typically used for one-time charges or a one-off invoice.
- Pix Automático (recurring): A recurring authorization (mandate) that lets Chargebee debit the customer for future subscription renewals without asking them to scan a new QR code each cycle.
To set up the EBANX gateway first, see Configure EBANX in Chargebee.
Integration options
You can integrate Pix via EBANX using the following methods:
| 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. |
| API | Process Pix payments using Chargebee APIs for a fully custom checkout and payment flow. |
Prerequisites
Before you enable Pix Payments via EBANX:
- Ensure EBANX is configured in your Chargebee site.
- Make sure you have a merchant account with EBANX that has Pix (and Pix Automático for recurring payments) enabled.
- Ensure your Merchant Country is set to Brazil and that you are transacting in BRL. Pix is available only for BRL payments in Brazil.
- Collect the following details from your customer, because EBANX requires them to process a Pix payment:
- Customer name
- Document ID (CPF or CNPJ)
- Billing address
Information
Document ID and billing address are mandatory for EBANX payments in Brazil. When you use Chargebee hosted checkout, these fields appear automatically once EBANX is selected through smart routing. See Additional mandatory settings for details.
Enable Pix via EBANX
Follow these steps to enable Pix in your EBANX gateway configuration:
- Log in to the Chargebee app.
- Go to Settings > Configure Chargebee > Payment Gateways and open your EBANX gateway.
- On the Configure EBANX page, turn on Pix under Payment methods.
- Configure the Notification URL in EBANX so that Chargebee receives payment status updates. Copy the Notification URL from the Configure EBANX page, then in your EBANX account go to Account Settings > Integration > Service URLs and paste it into the Status Change Notification URL field. Click Save Integration Settings in EBANX.
- Click Save and then click Apply on the Configure EBANX page.
Note
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.
Configure Smart Routing
When you enable Pix through EBANX, you must also set up Smart Routing so that BRL Pix payments are routed to your EBANX gateway. To configure this, follow these steps:
- On the Payment Gateways page under Settings > Configure Chargebee, click Manage rules under Smart Routing.
- Go to the Pix section and click Add a gateway for BRL.
- From the Choose a payment gateway dropdown, select the EBANX gateway instance that has Pix enabled.
- Click Save.
Note
Changes to Smart Routing rules affect only new payment methods added by your customers. Existing payment methods continue to be linked to their current gateway.
How Pix payments work
Pix is a push-based, asynchronous payment method. After the customer submits checkout, Chargebee creates the payment with EBANX, which returns a QR code and a payment link. The transaction stays in a pending state until the customer pays in their bank app and EBANX sends a status change notification (webhook) to Chargebee. Chargebee then marks the transaction as successful or failed and continues the subscription or invoice flow accordingly.
Pix Automático (recurring)
For recurring subscriptions, Chargebee uses Pix Automático, which creates a mandate (enrollment) alongside the first payment. This mandate authorizes Chargebee to collect future recurring charges from the customer without a new QR code each cycle.
- The mandate carries a maximum debit amount (
max_amount_floor) that caps how much can be debited in a single recurring charge. - Chargebee derives this amount from the upcoming renewal amount (the next invoice estimate, or the plan amount when an estimate is not available) and applies a buffer on top so that minor amount changes (for example, taxes or proration) do not exceed the authorized ceiling. This buffer is set to 10%.
- The mandate also carries the billing frequency, start date, and retry policy for failed recurring debits.
Note
For trial subscriptions, the recurring mandate amount is based on the amount that will be charged when the trial ends, not the trial (zero) amount, so that future renewals stay within the authorized ceiling.
Checkout flow
Your customer completes the following steps during checkout with Pix via EBANX:
- Review the order details on the Your order page and click Proceed To Checkout.
- Enter the email address on the Enter email to proceed page and click Next.
- Enter the billing address details on the Add your billing address page and click Next.
- On the Add your payment details page, select Pix as the payment method.
- Enter the payer details, select the Document type (for example, Brazil - CPF), enter the Document number, and click Next. These document fields appear only when EBANX is used as the gateway through smart routing.
- Review the order summary on the Complete your order page and click Pay & subscribe.
- The customer completes the payment in the Pix window by scanning the QR code or opening the payment link in their bank app. After the payment is submitted, the customer closes the window to return to Chargebee.
Payment features
The following table lists the features for this integration and their details.
| Feature | Description | Supported | Default state | Configuration or behavior |
|---|---|---|---|---|
| Integration sync mode | Defines the integration mode between Chargebee and EBANX, including how payment requests are processed and statuses are communicated. | Yes (asynchronous mode only) | Asynchronous | EBANX processes Pix payments asynchronously. Chargebee receives the final payment status through the EBANX status change notification. Webhooks are mandatory. |
| Capture settings | Payment processing involves two stages: authorization and capture. Capture settings determine when and how funds are collected after authorization. | Yes | Auto capture | No configuration is required. Pix is a push-based payment and is always auto-captured once the customer pays. |
| Recurring payments (Pix Automático) | Ability to collect recurring subscription charges without asking the customer to authorize each payment. | Yes | Enabled | A mandate is created at the first payment. Chargebee sends a maximum debit amount (max_amount_floor) derived from the renewal amount plus a buffer (10%). |
| Document ID collection | Collects the customer's tax/identity document (CPF or CNPJ) required to process payments in Brazil. | Yes | Enabled | Collected automatically in hosted checkout when EBANX is selected via smart routing. For Chargebee JS or API, collect and pass the document yourself. |
| Statement descriptor | A statement descriptor is the business name shown on a customer's statement. It helps customers recognize charges and reduces disputes. | No | Not applicable | EBANX does not support a dynamic statement/transaction descriptor. |
| Chargeback management | Processes chargeback events through webhooks and automatically applies configured actions on invoices and subscriptions. | No | Not applicable | Automated chargeback management is not supported for Pix. Refunds and returns are communicated through the EBANX status change notification. |
| Fraud management | Interprets fraud signals from the payment gateway to identify and flag high-risk transactions. | Yes | Enabled | Chargebee supports the EBANX Device Fingerprint as the Device ID for fraud management. See Fraud Management. |
| Transaction initiation type | Identifies whether a transaction is customer-initiated (CIT) or merchant-initiated (MIT). | Yes | Supported | The first Pix payment is customer-initiated when the customer completes checkout. Subsequent Pix Automático charges are merchant-initiated. |
| Error intelligence | Provides standardized categorization of payment failures. | Yes | Enabled | Supported for Pix via EBANX. No configuration is required. |
| Gateway transaction details | Provides access to raw gateway responses for transactions. | Yes | Enabled | Available on the transaction page under Error details. No configuration is required. |
Testing
Test in sandbox
Test the integration on your Chargebee test site before you enable it in production.
- Ensure EBANX is configured and Pix is turned on in your Chargebee test site, and that smart routing sends BRL Pix payments to EBANX.
- Ensure the Notification URL is configured in your EBANX account so that Chargebee receives status updates.
- Complete a Pix checkout using EBANX sandbox test data, confirm the payment in the EBANX sandbox simulator, and verify that the transaction status updates correctly in Chargebee.
Note
Because Pix is asynchronous, the transaction remains in a pending state until you confirm the payment in the sandbox simulator and EBANX sends the status change notification to Chargebee.
Test in production
Before you move to live:
- Ensure Pix Payments via EBANX is fully configured in EBANX and Chargebee, including the live Notification URL.
- Perform end-to-end testing with a real Brazilian bank account and CPF/CNPJ to validate the complete payment flow, including recurring Pix Automático renewals.
Reconciliation
For financial reconciliation between Chargebee and EBANX, use the Chargebee transaction field id_at_gateway, which maps to the EBANX transaction hash. Retrieve that value from the Chargebee transaction details, then locate the matching payment in EBANX.
Was this article helpful?