> ## 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

> 接受巴西客户使用 Pix 支付以 BRL 计费的一次性付款和订阅。了解二维码流程、测试和配置。

让巴西客户通过扫描二维码或粘贴 Pix 代码，从其银行应用中付款。Pix 是巴西的即时支付系统，由巴西中央银行（Banco Central do Brasil）创建。它全天候实时转移资金，包括周末和节假日。Dodo Payments 为以 BRL 计费的一次性付款和订阅提供 Pix。

## 为何提供 Pix？

<CardGroup cols={3}>
  <Card title="Dominant in Brazil" icon="chart-line">
    Pix 是巴西使用最广泛的支付方式，领先于信用卡和 boleto。巴西中央银行报告称，Pix 在 2025 年下半年处理了所有支付交易的 54.7%。
  </Card>

  <Card title="Instant Settlement" icon="bolt">
    Pix 转账可在几秒内完成，全年任何时间、任何日期均可使用，因此无需等待银行处理时间窗口。
  </Card>

  <Card title="Low Friction" icon="mobile">
    客户在其银行应用中扫描二维码或粘贴 Pix 代码。无需输入卡号或银行信息。
  </Card>
</CardGroup>

## 概述

BRL 的最低金额是结账页的最低金额，因此适用于 BRL 结账页上的每种支付方式。一次性付款的 BRL 支付金额还必须至少等值于 \$0.50，订阅支付则必须至少等值于 \$1.00。请参阅[最低金额](/features/adaptive-currency#minimum-amounts)。

| 详情 | 值 |
| :- | :- |
| **计费货币** | BRL |
| **支持的国家/地区** | 巴西 |
| **订阅** | 是 |
| **最低金额** | 0.50 BRL |
| **结算** | 即时 |

## 工作原理

```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
```

## 客户体验

1. 客户在结账时选择 **Pix**，并在 **Pix CPF** 字段中输入其 CPF（11 位巴西纳税人识别号）。
2. 客户确认付款。二维码会在全屏覆盖层中打开，二维码下方显示 Pix 代码和 **复制代码** 按钮。
3. 客户打开其银行应用，选择 Pix，然后扫描二维码或粘贴 Pix 代码。
4. 付款会在几秒内确认。
5. 结账检测到付款完成后，会将客户重定向到你的成功页面。

<Info>
  Pix QR 码会在一段时间后过期。如果客户未能及时付款，他们需要从你的网站重新开始结账流程。
</Info>

## 配置

```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 会显示在以 BRL 计费的一次性付款和订阅结账中。只有启用 [Adaptive Currency](/features/adaptive-currency) 后，Dodo Payments 才会以 BRL 计费，因此请在提供 Pix 前启用它。

## API 方法类型

| 类型 | 方法 | 国家/地区 |
| :- | :- | :- |
| `pix` | Pix | 巴西 |

## 测试

<Steps>
  <Step title="Enable Test Mode">
    关闭控制台侧边栏中的 **Live Mode** 开关，并使用在测试模式下创建的 API 密钥。
  </Step>

  <Step title="Set Billing Currency to BRL">
    启用 Adaptive Currency。然后，在 `allowed_payment_method_types` 中使用 `billing_currency: 'BRL'` 和 `pix` 创建结账会话。
  </Step>

  <Step title="Enter Test CPF and Scan the QR Code">
    在 **Pix CPF** 字段中输入 `00000000000`（11 个零）。结账页面会显示一个测试二维码。使用手机摄像头扫描它；无需使用 Pix 或银行应用。二维码会打开一个测试页面，你可以在其中模拟成功或失败的付款。
  </Step>
</Steps>

## 最佳实践

<AccordionGroup>
  <Accordion title="Set billing currency to BRL">
    Pix 仅适用于以 BRL 计费的结账，而 Dodo Payments 仅在启用 Adaptive Currency 时以 BRL 计费。启用 Adaptive Currency，以便向巴西客户以 BRL 报价和计费。
  </Accordion>

  <Accordion title="Provide card fallbacks">
    部分巴西客户更喜欢使用银行卡付款。将 `credit` 和 `debit` 作为备用支付方式。
  </Accordion>

  <Accordion title="Handle QR code expiration">
    Pix QR 码会在一段时间后过期。如果客户在二维码过期后返回，请为他们创建新的 checkout session。
  </Accordion>
</AccordionGroup>

## 故障排除

<AccordionGroup>
  <Accordion title="Pix not appearing at checkout">
    **检查：**

    1. 账单货币是否为 `BRL`？
    2. `pix` 是否包含在 `allowed_payment_method_types` 中？
    3. 客户的账单国家/地区是否为巴西（`BR`）？使用 Adaptive Currency 时，巴西账单地址会将账单货币设置为 BRL。
    4. 是否已启用 Adaptive Currency？
    5. 金额是否达到 0.50 BRL 的最低金额和 USD 最低金额？

    \*\*解决方案：\*\*Pix 仅在 BRL 结账中提供。请检查 API 请求中的货币和账单地址。
  </Accordion>

  <Accordion title="QR code expired">
    \*\*原因：\*\*客户未在过期时间窗口内完成付款。

    \*\*解决方案：\*\*客户需要从你的网站重新开始结账流程。要向他们发送新的支付链接，请创建新的 checkout session。
  </Accordion>

  <Accordion title="Payment pending">
    \*\*原因：\*\*大多数 Pix 付款会在几秒内确认，但银行偶尔可能会延迟转账。

    \*\*解决方案：\*\*使用 `payment.succeeded` 和 `payment.failed` webhooks 获取最终付款状态，而不要依赖返回重定向。如果付款在几分钟内未确认，请将其视为失败。
  </Accordion>
</AccordionGroup>

## 相关页面

<CardGroup cols={2}>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    查看所有支持的支付方式。
  </Card>

  <Card title="Adaptive Currency" icon="globe" href="/features/adaptive-currency">
    以客户的本地货币（包括 BRL）向其计费。
  </Card>

  <Card title="Checkout Guide" icon="book" href="/developer-resources/checkout-session">
    完整的结账实现指南。
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    异步处理付款确认。
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    测试数据和结账测试指南。
  </Card>
</CardGroup>


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