# Receber pagamento Pix (/docs/pix-processamento/tutoriais/receive-pix)



<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints/pix-operations/post_pix" title="POST /pix" />

  <QuickLink href="/docs/pix-processamento/endpoints/pix-operations/get_pix" title="GET /pix" />

  <QuickLink href="/docs/pix-processamento/webhooks" title="Webhooks" />

  <QuickLink href="/docs/pix-processamento/glossary" title="Glossário" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Cria cobrança&#x22;] --> B[&#x22;Exibe QR ao cliente&#x22;]
  B --> C[&#x22;Cliente paga no banco dele&#x22;]
  C --> D[&#x22;Callback COMPLETED&#x22;]
  D --> E[&#x22;Marca pedido como pago&#x22;]

  click A &#x22;/docs/pix-processamento/endpoints/pix-operations/post_pix&#x22; &#x22;POST /pix&#x22;
  click B &#x22;/docs/pix-processamento/endpoints/pix-operations/get_pix_qrcode&#x22; &#x22;GET /pix/qr-code&#x22;
  click D &#x22;/docs/pix-processamento/webhooks&#x22; &#x22;Webhooks&#x22;
  click E &#x22;/docs/pix-processamento/best-practices/idempotency&#x22; &#x22;Idempotência&#x22;

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

<Steps>
  <Step>
    ### Gerar cobrança [#gerar-cobrança]

    Endpoint: [`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix). Só `amount` é obrigatório; os demais campos enriquecem o QR e a reconciliação.

    <Tabs items="['curl', 'Node.js']">
      <Tab value="curl">
        ```bash
        curl -X POST https://api.payzu.processamento.com/v1/pix \
          -H "Authorization: Bearer $TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "amount": 99.90,
            "generatedName": "João da Silva",
            "generatedDocument": "12345678909",
            "callbackUrl": "https://seusite.com.br/webhooks/payzu",
            "clientReference": "pedido-2025-001",
            "virtualAccount": "loja-rj-01",
            "expiresIn": 600
          }'
        ```
      </Tab>

      <Tab value="Node.js">
        ```ts
        const res = await fetch('https://api.payzu.processamento.com/v1/pix', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            amount: 99.90,
            generatedName: 'João da Silva',
            generatedDocument: '12345678909',
            callbackUrl: 'https://seusite.com.br/webhooks/payzu',
            clientReference: 'pedido-2025-001',
            virtualAccount: 'loja-rj-01',
            expiresIn: 600,
          }),
        });
        const charge = await res.json();
        ```
      </Tab>
    </Tabs>

    Resposta:

    ```json
    {
      "id": "PAYZU20250817215911F49RDOBJ",
      "status": "PENDING",
      "amount": 99.90,
      "qrCodeText": "00020126870014br.gov.bcb.pix...",
      "qrCodeUrl": "https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU20250817215911F49RDOBJ",
      "clientReference": "pedido-2025-001",
      "virtualAccount": "loja-rj-01",
      "expiresAt": "2025-08-17T22:00:00.000Z"
    }
    ```
  </Step>

  <Step>
    ### Exibir QR Code ao cliente [#exibir-qr-code-ao-cliente]

    Duas formas:

    **Imagem direta**, use `qrCodeUrl` em `<img>`:

    ```html
    <img src="https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU2025..." />
    ```

    **Copia-e-cola**, exiba `qrCodeText` em input com botão:

    ```html
    <input value="00020126870014br.gov.bcb.pix2565..." readonly />
    <button onclick="navigator.clipboard.writeText(qrCodeText)">Copiar</button>
    ```

    <Callout type="info">
      PayZu gera QR **dinâmico** por cobrança.
    </Callout>
  </Step>

  <Step>
    ### Receber callback quando pago [#receber-callback-quando-pago]

    Quando o cliente concluir o Pix, a PayZu envia `POST` para sua `callbackUrl`:

    ```json
    {
      "id": "PAYZU20250817215911F49RDOBJ",
      "type": "DEPOSIT",
      "status": "COMPLETED",
      "amount": 99.90,
      "clientReference": "pedido-2025-001",
      "virtualAccount": "loja-rj-01",
      "endToEndId": "E60746948202508172200X7H4K2P9M5",
      "paidAt": "2025-08-17T22:00:12.000Z"
    }
    ```

    Handler de exemplo:

    <Tabs items="['Node.js (Express)', 'Python (Flask)']">
      <Tab value="Node.js (Express)">
        ```ts
        import express from 'express';
        const app = express();

        app.post('/webhooks/payzu', express.json(), async (req, res) => {
          const tx = req.body;

          if (await isProcessed(tx.id, tx.status)) return res.status(200).end();

          if (tx.type === 'DEPOSIT' && tx.status === 'COMPLETED') {
            await markOrderPaid(tx.clientReference, tx);
          }

          res.status(204).end();
        });
        ```
      </Tab>

      <Tab value="Python (Flask)">
        ```python
        from flask import Flask, request
        app = Flask(__name__)

        @app.post('/webhooks/payzu')
        def payzu_webhook():
            tx = request.get_json()
            if is_processed(tx['id'], tx['status']):
                return '', 200
            if tx['type'] == 'DEPOSIT' and tx['status'] == 'COMPLETED':
                mark_order_paid(tx['clientReference'], tx)
            return '', 204
        ```
      </Tab>
    </Tabs>

    <Callout type="warn">
      Responda em até **5 segundos** com `2xx`; a política completa de retry está em [Webhooks](/docs/pix-processamento/webhooks#sistema-de-retry).
    </Callout>
  </Step>

  <Step>
    ### Fallback por polling [#fallback-por-polling]

    Se o callback não chegar, consulte direto via [`GET /pix`](/docs/pix-processamento/endpoints/pix-operations/get_pix). Aceita `id`, `clientReference`, `endToEndId` ou `virtualAccount`, **use apenas um**.

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

      <Tab value="Node.js">
        ```ts
        const res = await fetch(
          `https://api.payzu.processamento.com/v1/pix?clientReference=pedido-2025-001`,
          {
            headers: {
              Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
              'Content-Type': 'application/json',
            },
          },
        );
        const charge = await res.json();
        ```
      </Tab>
    </Tabs>

    <Callout type="info">
      Polling deve ser fallback. Configure o callback como fonte primária.
    </Callout>
  </Step>

  <Step>
    ### Comprovante [#comprovante]

    Após o pagamento, baixe o comprovante oficial via [`GET /proof/{id}`](/docs/pix-processamento/endpoints/pix-operations/get_proof):

    ```bash
    curl "https://api.payzu.processamento.com/v1/proof/PAYZU20250817215911F49RDOBJ" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"
    ```
  </Step>
</Steps>

## Próximos passos [#próximos-passos]

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/webhooks" title="Webhooks" />

  <QuickLink href="/docs/pix-processamento/error-codes" title="Códigos de erro" />
</QuickLinks>