# Enviar Pix (/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="Consulta DICT" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Decide o destinatário&#x22;] --> B{&#x22;Como pagar?&#x22;}
  B -->|&#x22;Tenho chave Pix&#x22;| C[&#x22;Consulta DICT&#x22;]
  B -->|&#x22;Tenho QR Code&#x22;| D[&#x22;Ler QR (opcional)&#x22;]
  C --> E[&#x22;POST /withdraw&#x22;]
  D --> F[&#x22;POST /withdraw/qrcode&#x22;]
  E --> G[&#x22;Callback COMPLETED&#x22;]
  F --> G
  G --> H[&#x22;GET /withdraw/proof&#x22;]

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

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

## Caminho 1: por chave Pix [#caminho-1-por-chave-pix]

<Steps>
  <Step>
    ### Consultar a chave no DICT [#consultar-a-chave-no-dict]

    Antes de pagar, valide o destinatário consultando o DICT via [`GET /pix/key`](/docs/pix-processamento/endpoints/keys-and-dict/get_pix_key). Confirma que a chave existe e retorna o titular para você comparar com o esperado.

    <Tabs items="['curl', 'Node.js']">
      <Tab value="curl">
        ```bash
        curl "https://api.payzu.processamento.com/v1/pix/key?key=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('key', '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>

    Mais detalhes em [Consulta DICT](/docs/pix-processamento/best-practices/dict).
  </Step>

  <Step>
    ### Executar o saque [#executar-o-saque]

    Use [`POST /withdraw`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw) com a chave validada. `pixType` aceita: `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>

## Caminho 2: por QR Code [#caminho-2-por-qr-code]

<Steps>
  <Step>
    ### Ler o QR antes (opcional) [#ler-o-qr-antes-opcional]

    Se o QR foi escaneado de um cliente externo, extraia os dados antes de pagar via [`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 processa QR Code **dinâmico** e **estático**.
    </Callout>
  </Step>

  <Step>
    ### Executar o pagamento [#executar-o-pagamento]

    [`POST /withdraw/qrcode`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw_qrcode). Se o QR já tem valor embutido, `amount` pode ser omitido.

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

## Acompanhar status [#acompanhar-status]

O saque começa `PENDING` e evolui para `COMPLETED`, `CANCELED` ou `ERROR`. O callback chega em cada transição. Para consultar manualmente via [`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"
```

## Comprovante [#comprovante]

Após `COMPLETED`, baixe o comprovante oficial via [`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"
```

## Erros comuns [#erros-comuns]

| Erro                   | Resolução                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| Saldo insuficiente     | Confira [`GET /user/balance`](/docs/pix-processamento/endpoints/account/get_user_balance) antes |
| Chave Pix inválida     | Valide via DICT primeiro                                                                        |
| Valor abaixo do mínimo | `amount` ≥ R$ 0,01 (chave) ou ≥ R$ 0,10 (QR)                                                    |
| Destinatário diferente | Compare `dict.name` com o esperado antes de pagar                                               |