# 发送 Pix (/zh/docs/pix-processamento/tutoriais/send-pix)

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints/keys-and-dict/get_pix_key" title="GET /pix/key" method="GET" path="/pix/key" />

  <QuickLink href="/docs/pix-processamento/endpoints/withdrawals/post_withdraw" title="POST /withdraw" method="POST" path="/withdraw" />

  <QuickLink href="/docs/pix-processamento/endpoints/withdrawals/post_withdraw_qrcode" title="POST /withdraw/qrcode" method="POST" path="/withdraw/qrcode" />

  <QuickLink href="/docs/pix-processamento/best-practices/dict" title="DICT 查询" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;确定收款人&#x22;] --> B{&#x22;如何支付？&#x22;}
  B -->|&#x22;持有 Pix 密钥&#x22;| C[&#x22;查询 DICT&#x22;]
  B -->|&#x22;持有 QR Code&#x22;| D[&#x22;读取 QR（可选）&#x22;]
  C --> E[&#x22;POST /withdraw&#x22;]
  D --> F[&#x22;POST /withdraw/qrcode&#x22;]
  E --> G[&#x22;回调 COMPLETED&#x22;]
  F --> G
  G --> H[&#x22;GET /withdraw/proof&#x22;]

  click C &#x22;/zh/docs/pix-processamento/endpoints/keys-and-dict/get_pix_key&#x22; &#x22;GET /pix/key&#x22;
  click D &#x22;/zh/docs/pix-processamento/endpoints/keys-and-dict/post_pix_qrcode_read&#x22; &#x22;读取 QR&#x22;
  click E &#x22;/zh/docs/pix-processamento/endpoints/withdrawals/post_withdraw&#x22; &#x22;POST /withdraw&#x22;
  click F &#x22;/zh/docs/pix-processamento/endpoints/withdrawals/post_withdraw_qrcode&#x22; &#x22;POST /withdraw/qrcode&#x22;
  click G &#x22;/zh/docs/pix-processamento/webhooks&#x22; &#x22;Webhooks&#x22;
  click H &#x22;/zh/docs/pix-processamento/endpoints/withdrawals/get_withdraw_proof&#x22; &#x22;凭证&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style G fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

## 方式 1：通过 Pix 密钥 [#方式-1通过-pix-密钥]

<Steps>
  <Step>
    ### 在 DICT 中查询密钥 [#在-dict-中查询密钥]

    支付前，通过 [`GET /pix/key`](/docs/pix-processamento/endpoints/keys-and-dict/get_pix_key) 查询 DICT 以校验收款人。该接口确认密钥存在并返回持有人信息，便于与预期值进行比对。

    <Tabs items="['curl', 'Node.js']">
      <Tab value="curl">
        ```bash
        curl "https://api.payzu.processamento.com/v1/pix/key?pixKey=joao@example.com" \
          -H "Authorization: Bearer $TOKEN" \
          -H "Content-Type: application/json"
        ```
      </Tab>

      <Tab value="Node.js">
        ```ts
        const url = new URL('https://api.payzu.processamento.com/v1/pix/key');
        url.searchParams.set('pixKey', 'joao@example.com');

        const res = await fetch(url, {
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
        });
        const dict = await res.json();
        ```
      </Tab>
    </Tabs>

    更多详情请参阅 [DICT 查询](/docs/pix-processamento/best-practices/dict)。
  </Step>

  <Step>
    ### 执行付款 [#执行付款]

    使用 [`POST /withdraw`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw) 并传入已校验的密钥。`pixType` 支持：`cpf`、`cnpj`、`phone`、`email`、`evp`。

    <Tabs items="['curl', 'Node.js']">
      <Tab value="curl">
        ```bash
        curl -X POST https://api.payzu.processamento.com/v1/withdraw \
          -H "Authorization: Bearer $TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "amount": 250.00,
            "pixKey": "joao@example.com",
            "pixType": "email",
            "callbackUrl": "https://seusite.com.br/webhooks/payzu",
            "clientReference": "payout-2025-08-001",
            "description": "Pagamento referente ao pedido #1234"
          }'
        ```
      </Tab>

      <Tab value="Node.js">
        ```ts
        const res = await fetch('https://api.payzu.processamento.com/v1/withdraw', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            amount: 250.00,
            pixKey: 'joao@example.com',
            pixType: 'email',
            callbackUrl: 'https://seusite.com.br/webhooks/payzu',
            clientReference: 'payout-2025-08-001',
            description: 'Pagamento referente ao pedido #1234',
          }),
        });
        const withdraw = await res.json();
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## 方式 2：通过 QR Code [#方式-2通过-qr-code]

<Steps>
  <Step>
    ### 提前读取 QR（可选） [#提前读取-qr可选]

    如果 QR 是从外部客户端扫描所得，支付前可通过 [`POST /pix/qrcode/read`](/docs/pix-processamento/endpoints/keys-and-dict/post_pix_qrcode_read) 提取其数据。

    ```bash
    curl -X POST https://api.payzu.processamento.com/v1/pix/qrcode/read \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "qrCode": "00020126870014br.gov.bcb.pix..." }'
    ```

    <Callout type="info">
      PayZu 同时处理**动态**和**静态** QR Code。
    </Callout>
  </Step>

  <Step>
    ### 执行支付 [#执行支付]

    [`POST /withdraw/qrcode`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw_qrcode)。如果 QR 已内嵌金额，可省略 `amount`。

    ```bash
    curl -X POST https://api.payzu.processamento.com/v1/withdraw/qrcode \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "qrCode": "00020126870014br.gov.bcb.pix...",
        "amount": 100.00,
        "callbackUrl": "https://seusite.com.br/webhooks/payzu",
        "clientReference": "payout-qr-2025-08-001"
      }'
    ```
  </Step>
</Steps>

## 跟踪状态 [#跟踪状态]

Pix 付款初始为 `PENDING`，随后流转至 `COMPLETED`、`CANCELED` 或 `ERROR`。每次状态变更都会触发 callback。如需通过 [`GET /withdraw`](/docs/pix-processamento/endpoints/withdrawals/get_withdraw) 手动查询：

```bash
curl "https://api.payzu.processamento.com/v1/withdraw?clientReference=payout-2025-08-001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

## 凭证 [#凭证]

状态变为 `COMPLETED` 后，通过 [`GET /withdraw/proof/{id}`](/docs/pix-processamento/endpoints/withdrawals/get_withdraw_proof) 下载官方凭证：

```bash
curl "https://api.payzu.processamento.com/v1/withdraw/proof/PAYZU2025..." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

## 常见错误 [#常见错误]

| 错误       | 解决方案                                                                                   |
| -------- | -------------------------------------------------------------------------------------- |
| 余额不足     | 事先查询 [`GET /user/balance`](/docs/pix-processamento/endpoints/account/get_user_balance) |
| Pix 密钥无效 | 先通过 DICT 校验                                                                            |
| 金额低于最低限额 | `amount` ≥ R$ 0,01（密钥）或 ≥ R$ 0,10（QR）                                                  |
| 收款人不一致   | 支付前将 `dict.name` 与预期值进行比对                                                              |