Pix via Adyen

This feature is a Private Beta release. Contact Chargebee Support to enable Pix via Adyen for your live and test sites.

Pix is Brazil's instant payment system, operated by the Central Bank of Brazil. Chargebee supports Pix as a payment method through the Adyen payment gateway, for one-time payments and for subscriptions through Pix Automático.

When customers select Pix at checkout, they scan a Pix QR code or paste a Pix code in their banking app to pay. For a subscription, the same approval sets up a Pix Automático authorization for renewal payments. Payment status is confirmed through Adyen webhooks.

Pix via Adyen is a subscription-based payment method: Chargebee charges a saved Pix Automático authorization only for invoices of the subscription it was set up for.

Supported countries and currencies

Pix via Adyen supports the following country and currency:

Country	Currency
Brazil	BRL (Brazilian Real)

Payment features

The following features are available for Pix via Adyen:

Feature	Description	Supported	Default state	Configuration or behavior
Integration sync mode	Defines how payment requests are processed and statuses are communicated between Chargebee and Adyen.	Yes (asynchronous)	Asynchronous	Adyen processes Pix payments asynchronously. For a one-time payment, Chargebee receives the final status through the `AUTHORISATION` webhook. For a Pix Automático renewal, `AUTHORISATION` confirms that the debit is scheduled, and `CAPTURE` or `EXPIRE` reports the outcome after the billing date. 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 only supported capture setting for Pix via Adyen. No additional configuration is required.
Verification modes	Defines how payment methods are verified before processing.	Yes	Enabled	The customer approves the payment and, for a subscription, the Pix Automático authorization in their bank or payment app. No separate verification configuration is required in Chargebee.
Regulatory requirements	Rules set by the payment scheme or local regulation.	Yes	Enabled	The customer must provide their CPF or CNPJ (Brazilian tax ID). Pix Automático follows the Central Bank of Brazil rules for scheduling and retrying recurring debits.
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 Adyen.
Chargeback management	Handles chargeback events and applies configured actions on invoices and subscriptions.	No	Not applicable	Chargebee doesn't manage disputes for Pix via Adyen. Issue refunds when needed.
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 checkout payment is customer-initiated. Renewal payments are Merchant Initiated Transactions (MIT) collected through the saved Pix Automático authorization.
Error intelligence	Provides standardized categorization of payment failures.	Yes	Enabled	Available through Adyen payment and refusal 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.

Prerequisites

Before you set up Pix via Adyen in Chargebee, make sure that:

The Adyen payment gateway is configured in your Chargebee site, including webhook notifications.
Pix is added as a payment method for your merchant account in the Adyen Customer Area. To collect recurring payments, Pix Automático must also be enabled for the merchant account. Learn more
Your business has a local entity in Brazil. Adyen requires a local entity to accept Pix payments.
BRL (Brazilian Real) is enabled as a currency in your Chargebee site.
Your customers have a Brazilian bank account that supports Pix, and a CPF or CNPJ.

Integration options

You can integrate Pix via Adyen using the following methods:

Integration method	Description
Chargebee Hosted Pages	Accept Pix payments using Chargebee's hosted checkout pages with minimal integration effort.
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.

Supported token formats

This section is relevant if you're building a custom checkout.

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 Adyen for a saved Pix Automático authorization and used for renewal payments.	Yes	`payment_method[reference_id]`	`shopper_reference_id/recurring_detail_reference_id`
Gateway temporary token	Short-lived token format that can be converted to a permanent token.	No	Not applicable	Not applicable

Configure in Chargebee

Follow these steps to enable Pix via Adyen in your Chargebee site:

Log in to the Chargebee app.
Go to Settings > Configure Chargebee > Payment Gateways.
Select the relevant Adyen instance from the list.
On the Configure Adyen page, turn on Pix under the supported payment methods.
Click Apply to save your changes.

Configure Smart Routing

When you turn on Pix for an Adyen instance, Smart Routing for Pix payments in BRL is set to that instance automatically. If another gateway already handles Pix payments in BRL, update the rule manually:

Log in to the Chargebee app.
Go to Settings > Configure Chargebee > Payment Gateways.
Click Manage Rules under Smart Routing.
Go to the Pix section and click Add a Gateway for BRL. If a payment gateway is already assigned, click Edit.
From the Choose a payment gateway dropdown, select the Adyen instance with Pix turned on.
Click Save.

Configure webhook notifications

Chargebee relies on Adyen webhooks to receive the status of Pix payments, Pix Automático authorizations, and refunds. Pix via Adyen needs two webhooks in the Adyen Customer Area:

Standard webhook: Configure it as described in Configure webhook notifications for Adyen. Chargebee uses the AUTHORISATION, CAPTURE, EXPIRE, REFUND, and REFUND_FAILED events for Pix.
Recurring tokens life cycle events webhook: Adyen sends the saved Pix Automático authorization only through this webhook, so it's required for recurring payments. Chargebee uses the recurring.token.created event to save the authorization and the recurring.token.disabled event to learn that it was canceled.

Follow these steps to add the recurring tokens webhook:

Log in to your Adyen Customer Area.
Go to Developers > Webhooks and click + Webhook.
Select Recurring tokens life cycle events from the list of webhooks and click Add.
In the URL field, enter the same Chargebee notification URL that you use for the Standard webhook.
Under Security > Basic authentication, enter the same username and password that you use for the Standard webhook.
Click Save changes.

Checkout flow

Your customer completes the following steps at checkout when paying with Pix via Adyen:

The customer proceeds to the payment step of the checkout and selects Pix.
The customer enters their CPF or CNPJ and completes the order.
Chargebee displays the Pix QR code, the Pix copy-and-paste code, and a countdown. The QR code is valid for 15 minutes.
The customer scans the QR code or pastes the code in their bank or payment app, and approves the payment. For a subscription, the customer also approves the Pix Automático authorization in the same step.
After Adyen confirms the payment, the QR code closes and the order confirmation page appears.

Recurring payments

Pix via Adyen supports recurring subscription payments through Pix Automático. The customer approves a Pix Automático authorization for the subscription at checkout, and Chargebee uses it to collect renewal payments as Merchant Initiated Transactions (MIT), without asking the customer to scan a new QR code.

Set up a subscription with a trial

When the subscription starts with a free trial and nothing is due at checkout, the customer approves the Pix Automático authorization without paying anything. Chargebee collects the first payment through the authorization when the trial ends.

Billing frequencies

Pix Automático supports subscriptions billed weekly, monthly, quarterly, half-yearly, or yearly. Plans with other billing frequencies, such as every two weeks or every two months, can't use Pix Automático.

Renewal payment timing

Pix Automático debits are scheduled in advance. Adyen requires each renewal debit to be scheduled 2 to 10 days before the date on which the customer's bank debits the account. The renewal transaction stays In Progress in Chargebee until Adyen confirms the outcome on the billing date.

Dunning

If a Pix Automático renewal isn't collected, Chargebee retries it through real-time payments dunning. Adyen allows up to three retries for a failed Pix Automático debit. Each retry must be scheduled at least 24 hours after the retry request and within seven days of the original billing date.

To configure how Chargebee retries Pix renewals and what happens when the dunning period ends:

Log in to the Chargebee app.
Go to Settings > Configure Chargebee > Dunning for Online Payments.
In the Dunning for Real Time payments section, go to PIX and turn on Dunning.
Select the final actions for invoices and subscriptions when the dunning period ends.

See Dunning for more about dunning settings.

Test in sandbox

Use your Adyen test merchant account with Pix enabled, and a Chargebee test site with the Adyen test instance configured.

Use the test CPF 01234567890 from Adyen's test data.
The QR code generated in the Adyen test environment can't be scanned with a real bank app. To complete a test payment, go to Payments > Offers in the Adyen test Customer Area, select the payment by its PSP reference, and click Promote this offer to a sale. Adyen then sends the AUTHORISATION webhook to Chargebee.
Make sure both the Standard webhook and the Recurring tokens life cycle events webhook are configured for the test merchant account.

Refer to Adyen's Pix documentation for more test scenarios.

Test in production

Before you go live:

Make sure Pix is enabled for your live Adyen merchant account and, for recurring payments, that Pix Automático is also enabled.
Verify that the Standard webhook and the Recurring tokens life cycle events webhook are configured for the live merchant account.
Run an end-to-end test with a real Brazilian bank account that supports Pix, including a subscription checkout that sets up a Pix Automático authorization.

Reconcile transactions

For financial reconciliation between Chargebee and Adyen, use the Chargebee transaction field id_at_gateway, which maps to the Adyen pspReference.

Retrieve the id_at_gateway value from the Chargebee transaction details.
Locate the corresponding pspReference in your Adyen reports.
Match the transactions using this reference.

A Pix Automático renewal stays In Progress in Chargebee until Adyen confirms the debit on the billing date, so reconcile renewals after the billing date.

Error codes and troubleshooting

Adyen returns refusal reasons for failed Pix payments, and Chargebee shows them on the transaction page under Error details. For gateway error handling in Chargebee, see Payment errors.

Frequently Asked Questions (FAQs)

Can I refund a Pix payment?

Yes. You can issue full and partial refunds within 90 days of the payment. Refunds are asynchronous: the refund stays in progress until Adyen confirms it through the REFUND webhook. If the refund fails later, Adyen sends REFUND_FAILED, and Chargebee marks the refund as failed.

Can a customer use a saved Pix Automático authorization to pay another subscription?

No. A Pix Automático authorization is tied to the subscription it was set up for. Chargebee charges it only for invoices of that subscription, and charges invoices of other subscriptions to the customer's backup payment method. See Subscription-based payment methods.

Limitations and important points

Pix via Adyen is available only for BRL (Brazilian Real) transactions and customers with a Brazilian bank account.
The customer must provide their CPF or CNPJ at checkout.
A saved Pix Automático authorization is charged only for invoices of the subscription it was set up for. Invoices for one-time charges and invoices of other subscriptions are charged to the customer's backup payment method.
Pix can't be added through the Customer Portal or the Chargebee app. Customers must complete the Pix checkout flow.
A Pix Automático authorization can't be changed after the customer approves it. If you change the subscription's billing frequency, the customer must approve a new authorization.
Refunds are available within 90 days of the payment.