> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pix

> Accept Pix from Brazilian customers on one-time payments and subscriptions billed in BRL. Learn about the QR code flow, testing, and configuration.

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.

## Why Offer Pix?

<CardGroup cols={3}>
  <Card title="Dominant in Brazil" icon="chart-line">
    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.
  </Card>

  <Card title="Instant Settlement" icon="bolt">
    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.
  </Card>

  <Card title="Low Friction" icon="mobile">
    The customer scans a QR code or pastes a Pix code in their banking app. They don't enter card numbers or bank details.
  </Card>
</CardGroup>

## 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](/features/adaptive-currency#minimum-amounts).

| Detail | Value |
| :- | :- |
| **Billing Currency** | BRL |
| **Supported Countries** | Brazil |
| **Subscriptions** | Yes |
| **Min Amount** | 0.50 BRL |
| **Settlement** | Instant |

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Checkout
    participant Dodo
    participant Pix
    participant Bank

    Customer->>Checkout: Select Pix and enter CPF
    Checkout->>Dodo: Create payment
    Dodo->>Pix: Generate QR code
    Pix->>Customer: Display QR code / Pix code
    Customer->>Bank: Scan QR or paste code in banking app
    Bank->>Pix: Payment confirmed
    Pix->>Dodo: Success callback
    Dodo->>Checkout: Payment complete
```

## Customer Experience

1. The customer selects **Pix** at checkout and enters their CPF (the 11-digit Brazilian taxpayer ID) in the **Pix CPF** field.
2. 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.
3. The customer opens their banking app, selects Pix, and scans the QR code or pastes the Pix code.
4. The payment confirms within seconds.
5. Checkout detects the completed payment and redirects the customer to your success page.

<Info>
  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.
</Info>

## Configuration

```javascript theme={null}
// `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](/features/adaptive-currency) is enabled, so enable it before you offer Pix.

## API Method Type

| Type | Method | Country |
| :- | :- | :- |
| `pix` | Pix | Brazil |

## Testing

<Steps>
  <Step title="Enable Test Mode">
    Turn off the **Live Mode** switch in the dashboard sidebar, and use API keys created in test mode.
  </Step>

  <Step title="Set Billing Currency to BRL">
    Enable Adaptive Currency. Then create a checkout session with `billing_currency: 'BRL'` and `pix` in `allowed_payment_method_types`.
  </Step>

  <Step title="Enter Test CPF and Scan the QR Code">
    In the **Pix CPF** 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.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Provide card fallbacks">
    Some Brazilian customers prefer to pay by card. Include `credit` and `debit` as fallback payment methods.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pix not appearing at checkout">
    **Check:**

    1. Is the billing currency `BRL`?
    2. Is `pix` included in `allowed_payment_method_types`?
    3. Is the customer's billing country Brazil (`BR`)? With Adaptive Currency, a Brazilian billing address sets the billing currency to BRL.
    4. Is Adaptive Currency enabled?
    5. 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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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 the payment doesn't confirm within a few minutes, treat it as failed.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup cols={2}>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Adaptive Currency" icon="globe" href="/features/adaptive-currency">
    Bill customers in their local currency, including BRL.
  </Card>

  <Card title="Checkout Guide" icon="book" href="/developer-resources/checkout-session">
    Complete checkout implementation guide.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Handle payment confirmations asynchronously.
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    Test data and checkout testing guidance.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.