Pix via Stripe
This feature is a Private Beta release. Contact Chargebee Support to enable Pix via Stripe for your live and test sites.
Chargebee supports Pix through the Stripe payment gateway, letting you offer Brazilian customers a familiar local payment experience at checkout.
Pix is Brazil's instant payment system that enables 24/7 real-time transfers using various identifiers.
When a customer selects Pix during checkout:
- They're shown a QR code and authenticate and authorize the payment through their Brazilian bank or payment app, and save the Pix payment method during the initial payment.
- After authorization, Stripe redirects the customer back to your Chargebee site.
- Future payments can be initiated by the merchant without requiring the customer to approve each payment.
Supported countries and currencies
| Country | Supported currency |
|---|---|
| Brazil | BRL (Brazilian Real) |
Key features
- QR-based payment method. The customer completes the payment by scanning a QR code with their bank or payment app.
- Supports one-time payments (one-time charges) and recurring payments (subscriptions) through Pix Automático (merchant-initiated transactions).
- Supports BRL (Brazilian Real) as the payment currency.
- Available for customers with Brazilian bank accounts only.
Prerequisites
Before you set up Pix in Chargebee:
- Stripe is configured as a payment gateway in Chargebee.
- Pix is enabled in your Stripe account.
- The customer has a Pix key registered with their Brazilian bank. The CPF or CNPJ is mandatory on the payment details page.
Integration options
You can integrate Pix via Stripe 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 | Embed Pix as a payment method in your custom checkout using Chargebee.js. |
| API (Payment Intent) | Process Pix payments using Chargebee APIs for a fully custom checkout and payment flow. |
Configure Pix via Stripe in Chargebee
To enable Pix payments through Stripe in Chargebee:
- Log in to your Chargebee Billing site.
- Go to Settings > Configure Chargebee > Payment Gateway.
- Select Stripe from the list of configured gateways.
- On the Configure Stripe page, turn on Pix.
- Click Apply to save your changes.
Configure Smart Routing
After you turn on Pix, follow these steps to configure Smart Routing for it:
- Go to Settings > Configure Chargebee > Payment Gateways.
- Click Manage Rules under Smart Routing.
- Under the For Pix section, set the rule to route BRL payments to your Stripe account, then click Save.
Configuring webhooks
To keep your Chargebee–Stripe integration in sync, configure webhooks in Stripe. Webhooks let Chargebee receive real-time updates from Stripe when important events, such as refunds, occur.
For this integration to work correctly, enable the following events:
charge.refund.updated— notifies Chargebee when a refund transaction is created, fails, or is updated in Stripe.payment_intent.succeeded— notifies Chargebee when a payment is completed successfully.payment_intent.payment_failed— notifies Chargebee when a payment could not be completed.
These events ensure that payment and refund statuses are reflected accurately in your Chargebee account. Because Pix payments are asynchronous, Chargebee relies on the payment_intent.succeeded and payment_intent.payment_failed events to receive the final payment status.
Payment workflow
Your customer completes the following steps at checkout when paying with Pix via Stripe:
- The customer reviews the order details on the Your order page and clicks Proceed To Checkout.
- The customer enters their email address to proceed and clicks Next.
- The customer enters their billing address on the Add your billing address page and clicks Next.
- On the Add your payment details page, the customer selects Pix, enters their CPF/CNPJ (mandatory), and clicks Next.
- The customer reviews the order summary on the Complete your order page and clicks Pay.
- The customer scans the displayed Pix QR code with their Brazilian bank or payment app, or copies the Pix code to complete the payment.
- The customer authorizes the payment through their Brazilian bank or payment app.
- Once the payment is authorized, the page automatically closes and the customer is redirected back to Chargebee.
Note
These screenshots show the Pix checkout flow in Stripe's test environment. In production, customers complete the payment by scanning the live QR code with their bank or payment app.
Recurring payments (Pix Automático)
Pix via Stripe supports recurring billing through Pix Automático (merchant-initiated transactions):
- Customers authorize a Pix Automático mandate and save their Pix payment method during the initial payment.
- Future payments can then be initiated by the merchant without requiring the customer to approve each payment or scan a new QR code.
- Pix Automático payments are asynchronous and are processed by the customer's bank before reaching a final status.
- Processing time is typically 1–3 business days for the bank to process the payment.
- Chargebee relies on webhooks to receive the final payment status:
payment_intent.succeeded— the payment completed successfully.payment_intent.payment_failed— the payment could not be completed.
Payment features
The following features are supported for Pix via Stripe.
| Feature | Description | Supported | Default state | Configuration or behavior |
|---|---|---|---|---|
| Integration sync mode | Defines how payment requests are processed and statuses are communicated between Chargebee and Stripe. | Yes (asynchronous) | Asynchronous | Stripe processes Pix payments asynchronously. A Pix Automático payment is processed by the customer's bank and can take 1–3 business days to reach a final status. Chargebee receives the final status through the payment_intent.succeeded and payment_intent.payment_failed webhooks, and refund updates through the charge.refund.updated event. Webhook configuration is mandatory. |
| Capture settings | Payment processing involves two stages: authorization and capture. Capture settings determine when funds are collected after authorization. | Yes | Auto capture | Auto capture is the default and only supported capture setting for Pix via Stripe. No additional configuration is required. |
| Verification modes | Defines how payment methods are verified before processing. | Yes | Enabled | The customer authorizes the payment through their Brazilian bank or payment app. No separate verification configuration is required in Chargebee. |
| Statement descriptor | Displays the business name on the customer's bank statement, helping them recognize charges and reducing disputes. | No | Not applicable | Not applicable to Pix via Stripe. |
| Chargeback management | Handles chargeback events and applies configured actions on invoices and subscriptions. | No | Not applicable | Chargebee does not manage Pix disputes for this integration. Stripe Pix disputes are limited, cannot be challenged, and can result in Stripe removing funds. |
| Fraud management | Uses gateway fraud signals to identify and flag high-risk transactions. | No | Not applicable | No Pix-specific fraud configuration is available in Chargebee. |
| Transaction initiation type | Identifies whether a transaction is customer-initiated (CIT) or merchant-initiated (MIT). | Yes | Supported | The initial payment is customer-initiated when the customer authorizes a Pix Automático mandate. Subsequent recurring charges are merchant-initiated using the stored Stripe payment method. |
| Error intelligence | Provides standardized categorization of payment failures. | Yes | Enabled | Available through Stripe payment responses. 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. |
| Adding payment methods in the Chargebee dashboard | Allows a payment method to be added in Chargebee when details are collected outside checkout. | No | Not applicable | Customers must complete the Pix checkout flow. Pix can't be added from the Chargebee dashboard. |
Supported token formats
This section is relevant if you're building a custom checkout or migrating payment methods from another provider to Stripe.
| Token type | Description | Supported | Token field | Token format |
|---|---|---|---|---|
| Chargebee Payment Intent | Recommended token format when building a custom checkout using Chargebee.js. | Yes | payment_intent[id] | payment_intent_id |
| Chargebee token | Legacy token format supported for selected payment methods and gateways with Chargebee.js. Not recommended for new implementations. | No | token_id | Not applicable |
| Gateway permanent token | Permanent reference provided by Stripe and used for subsequent merchant-initiated recurring payments. | Yes | payment_method[reference_id] | customer_id/payment_method_id |
| Gateway temporary token | Short-lived token format that can be converted to a permanent token. | No | Not applicable | Not applicable |
Testing
Sandbox testing
Refer to Stripe's Pix documentation for instructions on testing Pix in the Stripe test environment. Make sure webhooks are configured to receive the payment_intent.succeeded, payment_intent.payment_failed, and charge.refund.updated events.
Production testing
Before you go live:
- Make sure Pix is enabled in your Stripe live account.
- Verify that webhook configuration is complete (required for payment status and refund settlement updates).
- Run end-to-end testing using a real Brazilian bank account that supports Pix.
Reconciliation
For financial reconciliation between Chargebee and Stripe, use the Chargebee transaction field id_at_gateway, which maps to the Stripe PaymentIntent ID.
To reconcile transactions:
- Retrieve the
id_at_gatewayvalue from the Chargebee transaction details. - Locate the corresponding transaction in your Stripe Dashboard or reports.
- Match transactions using this reference to keep your records consistent.
Transaction limits
A single Pix payment must be at least 0.50 BRL and no more than 3,000 USD.
For recurring (MIT) payments, the amount you can charge is limited to the amount the customer authorizes during mandate creation. If you charge more than the authorized amount, the payment fails. Additionally, a single customer can't transact more than 10,000 USD per month with any single business.
Limitations and important points
- Pix can't be added as a payment method through the customer portal or the Chargebee app. Customers must complete the Pix checkout flow.
- Pix supports recurring billing through Pix Automático. The customer authorizes a mandate during the initial payment, and subsequent charges are processed without the customer approving each payment or scanning a new QR code.
- Pix Automático payments are asynchronous. A payment is processed by the customer's bank and can take 1–3 business days to reach a final status.
- Pix is available only to customers with a Brazilian bank account and is subject to Brazilian foreign exchange control regulations.
- The customer must provide their CPF or CNPJ on the payment details page.
- Chargebee does not manage Pix disputes. Stripe Pix disputes are limited, cannot be challenged, and can result in Stripe removing funds.
- Pix is available only for BRL (Brazilian Real) transactions.
Was this article helpful?