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

# Receber Pix (Cash-in)

> Fluxo completo de recebimento: criar cobrança, gerar QR Code, monitorar pagamento via webhook e consultar status.

## Visão geral do fluxo

```mermaid theme={null}
sequenceDiagram
  participant S as Seu sistema
  participant CP as ClearPago
  participant P as Pagador
  participant B as BaaS

  S->>CP: POST /api/pix/cash-in
  CP-->>S: 201 {id, status:PENDING, pixCode}
  S->>S: Persiste id e externalId
  S->>P: Exibe QR Code / pixCode
  P->>B: Paga Pix
  B->>CP: Webhook CashIn (CONFIRMED)
  CP->>CP: status → PAID, grava ledger
  CP->>S: POST /webhooks/pix {event_type:pix_cash_in, status:PAID}
  S->>S: Valida assinatura → libera pedido
```

## Passo 1 — Criar a cobrança

```bash theme={null}
curl -X POST https://api.clearpago.com.br/api/pix/cash-in \
  -H "Authorization: Bearer <seu_api_token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: req-cash-in-001" \
  -d '{
    "transaction": {
      "value": 150.75,
      "externalId": "pedido-12345",
      "description": "Pagamento Pedido #12345",
      "expirationTime": 3600,
      "generateQrCode": true
    },
    "payer": {
      "fullName": "João da Silva",
      "document": "123.456.789-00"
    }
  }'
```

**Resposta `201`:**

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING",
  "pixCode": "00020101021226870014br.gov.bcb.pix...",
  "expirationDate": "2026-04-01T13:00:00.000Z",
  "externalId": "pedido-12345"
}
```

<Warning>
  **Persista o `id` imediatamente.** Ele é necessário para consultas, cancelamentos e devoluções. O `externalId` é a sua chave de negócio — guarde ambos.
</Warning>

### Parâmetros importantes

| Campo                        | Obrigatório | Notas                                                              |
| ---------------------------- | ----------- | ------------------------------------------------------------------ |
| `transaction.value`          | Sim         | Valor em **BRL** (ex.: `150.75`).                                  |
| `transaction.externalId`     | Sim         | Deve ser **único** por cobrança. Duplicidade retorna `409`.        |
| `transaction.expirationTime` | Não         | Validade em segundos. Se omitido, a plataforma define o padrão.    |
| `transaction.generateQrCode` | Não         | `true` para gerar `pixCode` (EMV) na resposta.                     |
| `payer.document`             | Não         | CPF/CNPJ do pagador. `TODO: confirmar obrigatoriedade com a spec.` |

## Passo 2 — Exibir o QR Code

O campo `pixCode` retornado é a **string EMV** (pix copia e cola). Use uma biblioteca de QR Code para renderizar a imagem ao pagador ou exibir o copia e cola diretamente.

Exiba `expirationDate` formatado para o usuário. Após a expiração, o status será `EXPIRED` e um novo cash-in precisará ser criado.

## Passo 3 — Receber o webhook

Quando o pagamento for liquidado, você receberá:

```http theme={null}
POST https://seu-sistema.com/webhooks/pix
Content-Type: application/json
Digital-Signature: <base64 ECDSA P-256 SHA-256>

{
  "event_type": "pix_cash_in",
  "event": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "pedido-12345",
    "status": "PAID",
    "value_cents": 15075,
    "end_to_end_id": "E00416968202504011200rjzxxzSSTD9",
    "payer_name": "João da Silva",
    "fee_amount_cents": 5,
    "confirmed_at": "2026-04-01T12:10:00.000000000Z",
    "created_at": "2026-04-01T12:00:00.000000000Z"
  }
}
```

**O que fazer ao receber:**

1. [Verificar a assinatura](/guides/verify-webhook-signatures) (`Digital-Signature`) **antes de qualquer lógica**.
2. Responder **2xx** em até \~5 segundos.
3. Enfileirar o processamento se necessário.
4. Verificar idempotência: `event_type` + `event.id` + status.
5. Se `status == "PAID"` e a verificação passar: liberar o pedido, enviar e-mail, etc.

<Note>
  O webhook também pode chegar com `status: "FAILED"` para cobranças que expiraram ou falharam definitivamente. Trate ambos os casos.
</Note>

## Passo 4 — Consultar o status (opcional)

Sempre que houver dúvida sobre o estado atual:

```bash theme={null}
curl https://api.clearpago.com.br/api/pix/cash-in/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <seu_api_token>"
```

Use como fall-back quando:

* O webhook não chegou dentro do tempo esperado.
* Você precisa confirmar um estado antes de uma ação crítica.
* O status está em `PROVIDER_RESULT_UNKNOWN` ou `RECONCILIATION_REQUIRED`.

## Quando considerar o pagamento confirmado

| Condição                                              | Ação                                  |
| ----------------------------------------------------- | ------------------------------------- |
| Webhook `pix_cash_in` com `status: PAID`              | Liberar o pedido.                     |
| `GET /api/pix/cash-in/{id}` retorna `PAID`            | Confirmar e liberar.                  |
| Status `EXPIRED`                                      | Criar nova cobrança se necessário.    |
| Status `FAILED`                                       | Registrar falha, notificar o usuário. |
| `PROVIDER_RESULT_UNKNOWN` / `RECONCILIATION_REQUIRED` | **Aguardar.** Não liberar o pedido.   |

## Devoluções (refund-in)

Se precisar devolver um recebimento pago, veja [Devolver um cash-in](/guides/refund-a-cash-in).

## Referências

* [POST /api/pix/cash-in](/api-reference/create-cash-in)
* [GET /api/pix/cash-in/{id}](/api-reference/get-cash-in)
* [Modelo de status](/core-concepts/status-model)
* [Verificar assinaturas](/guides/verify-webhook-signatures)