Pix

Let Brazilian customers pay from their banking app by scanning a QR code or pasting a Pix code. Pix is Brazil’s instant payment system, created by the Central Bank of Brazil (Banco Central do Brasil). It moves money in real time, 24 hours a day, including weekends and holidays. Dodo Payments offers Pix on one-time payments and subscriptions billed in BRL. Subscriptions run on Pix Automático: the customer authorizes a recurring mandate in their banking app, and each renewal is debited after a 3-day notice.

Why Offer Pix?

Dominant in Brazil

Pix is the most-used payment method in Brazil, ahead of credit cards and boleto. The Central Bank of Brazil reports that Pix carried 54.7% of all payment transactions in the second half of 2025.

Instant Settlement

Pix transfers complete in seconds, at any hour and on any day of the year, so there is no bank processing window to wait for.

Low Friction

The customer scans a QR code or pastes a Pix code in their banking app. They don’t enter card numbers or bank details.

Overview

The minimum is the checkout minimum for BRL, so it applies to every payment method on a BRL checkout. A BRL payment must also be at least the equivalent of $0.50 for one-time payments and $1.00 for subscriptions. See Minimum Amounts.

Detail	Value
Billing Currency	BRL
Supported Countries	Brazil
Subscriptions	Yes, through Pix Automático
Min Amount	0.50 BRL
Max Amount	BRL equivalent of US$3,000 per payment
IOF	3.5%, paid by the customer on top of the amount
One-Time Confirmation	Seconds
Renewal Confirmation	3 days after the billing date, up to 7 days with retries

How It Works

Customer Experience

The customer selects Pix at checkout and enters their CPF (the 11-digit Brazilian taxpayer ID) or CNPJ (the 14-digit company ID) in the CPF or CNPJ field.
Checkout shows the IOF fee and the total the customer’s bank will debit. See Brazilian IOF Tax.
The customer confirms the payment. A QR code opens in a full-screen overlay, with the Pix code and a Copy the code button below it.
The customer opens their banking app, selects Pix, and scans the QR code or pastes the Pix code.
The payment confirms within seconds.
Checkout detects the completed payment and redirects the customer to your success page.

The Pix QR code expires after a limited time. If the customer doesn’t pay in time, they need to start a new checkout from your site.

Subscriptions with Pix Automático

A Pix subscription starts with a one-time Pix payment that also enrolls the customer in a recurring mandate. Renewals are then debited from the customer’s bank account without a QR code.

How Pix Automático Works

The customer authorizes the mandate in their banking app when they pay for the first time. Each renewal then waits 3 days after a pre-debit notification before the bank debits the funds: In their banking app, the customer sees the mandate under the name Dodo Payments Inc, because Dodo Payments is the Merchant of Record.

Mandate Terms

Dodo Payments sets the mandate terms. There is no API or dashboard setting for a Pix mandate, and the mandate_min_amount_inr_paise field applies only to Indian-issued cards.

Term	Value
Charge frequency	One charge per month
Amount	A maximum amount per charge, authorized by the customer
Expiry	None. The mandate stays active until the customer revokes it.

The mandate allows one debit per month, so the subscription’s billing interval must be a month or longer. A renewal that falls in the same month as a previous Pix charge fails with the error You can only schedule one Pix payment per billing cycle.

Don’t offer Pix on daily or weekly subscription plans. The first payment succeeds, but renewals fail. Remove pix from allowed_payment_method_types on those checkouts.

The 3-Day Renewal Delay

A Pix renewal completes about 3 days after the billing date. This is the main difference from a one-time Pix payment, which confirms in seconds:

Charge Initiated (Day 0)

On the billing date, Dodo Payments initiates the charge against the mandate. The payment enters the processing state and Dodo Payments sends the payment.processing webhook.

Pre-Debit Notification

The customer’s bank notifies them of the upcoming debit, with the exact amount and an option to cancel it. The bank sends this notification; you don’t need to do anything.

Debit (Day 3)

The bank debits the customer’s account. If the debit fails for a temporary reason, such as insufficient funds, the bank retries once a day for the next 3 days. The payment stays in processing during the retries.

Final Status (Day 3 to Day 7)

The payment moves to succeeded or failed, and Dodo Payments sends the matching webhook. A failed renewal follows the usual Payment Retries and Dunning flow.

Use the payment.succeeded and payment.failed webhooks for the final status of a renewal. Don’t treat a renewal in processing as failed: it can stay there for up to 7 days. While the renewal is in processing, the subscription stays active. Dodo Payments waits a maximum of 8 days after it creates the payment. For what occurs after the wait, see On Hold State.

Trials

On a subscription with a trial, the customer authorizes the mandate in their banking app without paying. The first charge after the trial follows the same 3-day renewal flow, so it completes about 3 days after the trial ends.

Customer Cancellation

The customer can stop a Pix subscription from their banking app in two ways:

Cancel a single debit. During the 3-day notification window, the customer can decline the upcoming debit. That renewal fails with the error The Pix payment attempt of this PaymentIntent has been canceled by the customer, and the mandate stays active for later renewals.
Revoke the mandate. The customer can cancel the mandate itself. Every later renewal then fails with the error Only active mandates can be used with PaymentIntents, and the subscription follows the failed-renewal flow.

In both cases, to keep the subscription, the customer must update their payment method through a new checkout, which creates a new mandate.

Brazilian IOF Tax

IOF (Imposto sobre Operações Financeiras) is a Brazilian tax of 3.5% on international transactions. The customer pays it on top of every Pix payment, including each subscription renewal. For a 100 BRL payment, the customer’s bank debits 103.50 BRL, and the payment amount stays 100 BRL. Checkout shows the IOF fee and the total due before the customer confirms. There is no option to absorb the IOF on the customer’s behalf.

Amount Limits

A single Pix payment can be at most the BRL equivalent of US$3,000. A payment above this limit fails with the error Amount must be no more than $3,000.00 usd.

Configuration

// `client` is an initialized DodoPayments client.
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['pix', 'credit', 'debit'],
  billing_currency: 'BRL',
  return_url: 'https://example.com/success'
});

Pix appears on one-time and subscription checkouts billed in BRL. Dodo Payments bills in BRL only when Adaptive Currency is enabled, so enable it before you offer Pix. A subscription checkout needs no extra parameter: the mandate is created as part of the first payment.

API Method Type

Type	Method	Country
`pix`	Pix	Brazil

Testing

Enable Test Mode

Turn off the Live Mode switch in the dashboard sidebar, and use API keys created in test mode.

Set Billing Currency to BRL

Enable Adaptive Currency. Then create a checkout session with billing_currency: 'BRL' and pix in allowed_payment_method_types.

Enter Test CPF and Scan the QR Code

In the CPF or CNPJ field, enter 00000000000 (11 zeros). Checkout shows a test QR code. Scan it with your phone’s camera; a Pix or banking app isn’t needed. The QR code opens a test page where you can simulate a successful or failed payment.

Best Practices

Set billing currency to BRL

Pix works only on checkouts billed in BRL, and Dodo Payments bills in BRL only when Adaptive Currency is enabled. Enable Adaptive Currency so customers in Brazil are quoted and billed in BRL.

Provide card fallbacks

Some Brazilian customers prefer to pay by card. Include credit and debit as fallback payment methods.

Offer Pix on monthly or longer subscription plans

A Pix mandate allows one debit per month. Leave pix out of allowed_payment_method_types on daily and weekly plans, where renewals fail.

Wait for the webhook on renewals

A Pix renewal stays in processing for about 3 days, and up to 7 with retries. Keep the customer’s access during this window and act on payment.succeeded or payment.failed.

Handle QR code expiration

Pix QR codes expire after a limited time. If a customer comes back after the code expires, create a new checkout session for them.

Troubleshooting

Pix not appearing at checkout

Check:

Is the billing currency BRL?
Is pix included in allowed_payment_method_types?
Is the customer’s billing country Brazil (BR)? With Adaptive Currency, a Brazilian billing address sets the billing currency to BRL.
Is Adaptive Currency enabled?
Does the amount meet the 0.50 BRL minimum and the USD minimum?

Solution: Pix is offered only on BRL checkouts. Check the currency and billing address in your API request.

QR code expired

Cause: The customer didn’t complete the payment within the expiration window.Solution: The customer needs to start a new checkout from your site. To send them a new payment link, create a new checkout session.

One-time payment pending

Cause: Most Pix payments confirm within seconds, but a bank can occasionally delay a transfer.Solution: Use the payment.succeeded and payment.failed webhooks for the final payment status instead of the return redirect. If a one-time payment doesn’t confirm within a few minutes, treat it as failed.

Renewal stuck in processing

Cause: This is expected. A Pix renewal waits 3 days after the pre-debit notification, and bank retries can extend this to 7 days.Solution: Wait for payment.succeeded or payment.failed. A renewal in processing is neither paid nor failed.

Renewal failed with an inactive mandate

Cause: The customer revoked the Pix mandate in their banking app. The renewal fails with the error Only active mandates can be used with PaymentIntents.Solution: The subscription follows the failed-renewal flow. To continue, the customer must update their payment method through a new checkout, which creates a new mandate.

Renewal failed with one Pix payment per billing cycle

Cause: The subscription bills more than once a month, but the Pix mandate allows one debit per month.Solution: Remove pix from allowed_payment_method_types on daily and weekly plans. Existing customers on those plans need to switch to a card.

Payment above the Pix limit

Cause: The amount is above the BRL equivalent of US$3,000. The payment fails with the error Amount must be no more than $3,000.00 usd.Solution: Offer credit and debit as fallbacks for high-value checkouts.

Payment Methods Overview

See all supported payment methods.

Adaptive Currency

Bill customers in their local currency, including BRL.

Subscriptions

Subscription states, trials, plan changes, and the on-hold flow.

Payment Retries

How failed renewals are retried before dunning starts.

Checkout Guide

Complete checkout implementation guide.

Webhooks

Handle payment confirmations asynchronously.

Testing Process

Test data and checkout testing guidance.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Why Offer Pix?

Dominant in Brazil

Instant Settlement

Low Friction

Overview

How It Works

Customer Experience

Subscriptions with Pix Automático

How Pix Automático Works

Mandate Terms

The 3-Day Renewal Delay

Trials

Customer Cancellation

Brazilian IOF Tax

Amount Limits

Configuration

API Method Type

Testing

Best Practices

Troubleshooting

Payment Methods Overview

Adaptive Currency

Subscriptions

Payment Retries

Checkout Guide

Webhooks

Testing Process

​Why Offer Pix?

Dominant in Brazil

Instant Settlement

Low Friction

​Overview

​How It Works

​Customer Experience

​Subscriptions with Pix Automático

​How Pix Automático Works

​Mandate Terms

​The 3-Day Renewal Delay

​Trials

​Customer Cancellation

​Brazilian IOF Tax

​Amount Limits

​Configuration

​API Method Type

​Testing

​Best Practices

​Troubleshooting

​Related Pages

Payment Methods Overview

Adaptive Currency

Subscriptions

Payment Retries

Checkout Guide

Webhooks

Testing Process

Why Offer Pix?

Overview

How It Works

Customer Experience

Subscriptions with Pix Automático

How Pix Automático Works

Mandate Terms

The 3-Day Renewal Delay

Trials

Customer Cancellation

Brazilian IOF Tax

Amount Limits

Configuration

API Method Type

Testing

Best Practices

Troubleshooting

Related Pages