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

# Enviar Pix por QR Code (Cash-out QR)

> Fluxo de pagamento a partir de string EMV (pix copia e cola); diferenças em relação ao cash-out por chave.

## Visão geral

O cash-out por QR Code processa um pagamento a partir de uma **string EMV** (pix copia e cola) — o código que começa com `000201...`. O ciclo de vida e os webhooks são idênticos ao [cash-out por chave](/guides/send-pix-cash-out-key); a diferença está no payload de criação.

Use este fluxo quando:

* O destinatário fornece um QR Code estático ou dinâmico.
* Você precisa pagar uma cobrança Pix emitida por terceiros.
* O valor já está codificado na string EMV.

## Criar o pagamento

```bash theme={null}
curl -X POST https://api.clearpago.com.br/api/pix/cash-out-qrcode \
  -H "Authorization: Bearer <seu_api_token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: req-qrpay-001" \
  -d '{
    "value": 99.90,
    "externalId": "pagamento-qr-456",
    "qrCode": "00020101021226870014br.gov.bcb.pix2565...",
    "description": "Pagamento via QR Code",
    "name": "Loja XYZ",
    "document": "00.000.000/0001-00"
  }'
```

**Resposta `201`:**

```json theme={null}
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "CREATED",
  "externalId": "pagamento-qr-456"
}
```

### Campos

| Campo         | Obrigatório | Notas                                                    |
| ------------- | ----------- | -------------------------------------------------------- |
| `value`       | Sim         | Valor em **BRL** a pagar. Deve ser consistente com o QR. |
| `externalId`  | Sim         | Único por operação. `409` em duplicata.                  |
| `qrCode`      | Sim         | String **EMV completa** (pix copia e cola).              |
| `description` | Não         | Descrição interna da operação.                           |
| `name`        | Não         | Nome do beneficiário para referência.                    |
| `document`    | Não         | CPF/CNPJ do beneficiário.                                |

<Warning>
  **Atenção ao campo `value`:** O valor informado deve ser **coerente** com o valor codificado no QR Code. QR Codes com valor fixo não permitem alteração. `TODO: confirmar validação de consistência de valor com a spec.`
</Warning>

## Diferenças em relação ao cash-out por chave

| Aspecto            | Cash-out por chave                      | Cash-out por QR Code                    |
| ------------------ | --------------------------------------- | --------------------------------------- |
| Rota               | `POST /api/pix/cash-out`                | `POST /api/pix/cash-out-qrcode`         |
| Estrutura do corpo | `transaction` + `recipient` aninhados   | campos na raiz                          |
| Endereçamento      | `pixKey` + `pixKeyType`                 | `qrCode` (string EMV)                   |
| Ciclo de vida      | Idêntico                                | Idêntico                                |
| Webhooks           | `pix_cash_out`, `pix_cash_out_reversal` | `pix_cash_out`, `pix_cash_out_reversal` |

## Ciclo de vida e webhooks

O ciclo de vida é o mesmo do cash-out por chave:

1. `201` com estado inicial (`CREATED`, `RESERVED`, etc.).
2. Despacho ao BaaS.
3. Webhook `pix_cash_out` com `CONFIRMED` ou `FAILED`.
4. Em caso de reversão posterior: webhook `pix_cash_out_reversal` com `REVERSED`.

Consulte [Enviar Pix por chave](/guides/send-pix-cash-out-key) para detalhes do pipeline, estados ambíguos e reconciliação.

## Cuidados práticos

* **QR expirado:** se o QR Code já expirou, a criação falhará com `4xx` ou o BaaS rejeitará. Obtenha uma nova string EMV junto ao emissor.
* **QR já pago:** QR Codes dinâmicos de uso único são rejeitados se já foram liquidados.
* **Não reutilize `externalId`:** cada tentativa de pagamento deve usar um `externalId` distinto.

## Referências

* [POST /api/pix/cash-out-qrcode](/api-reference/create-cash-out-qrcode)
* [GET /api/pix/cash-out/{id}](/api-reference/get-cash-out)
* [Enviar por chave (fluxo completo)](/guides/send-pix-cash-out-key)
* [Modelo de status](/core-concepts/status-model)