Receber Pix (Cash-in)

Visão geral do fluxo

Passo 1 — Criar a cobrança

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:

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

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

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á:

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:

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

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

Passo 4 — Consultar o status (opcional)

Sempre que houver dúvida sobre o estado atual:

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.

Início

Introdução

Conceitos

Guias

Referência de API

Webhooks

Ledger e Reconciliação

Erros

Go-live

FAQ

Receber Pix (Cash-in)

Visão geral do fluxo

Passo 1 — Criar a cobrança

Parâmetros importantes

Passo 2 — Exibir o QR Code

Passo 3 — Receber o webhook

Passo 4 — Consultar o status (opcional)

Quando considerar o pagamento confirmado

Devoluções (refund-in)

Referências

​Visão geral do fluxo

​Passo 1 — Criar a cobrança

​Parâmetros importantes

​Passo 2 — Exibir o QR Code

​Passo 3 — Receber o webhook

​Passo 4 — Consultar o status (opcional)

​Quando considerar o pagamento confirmado

​Devoluções (refund-in)

​Referências

Visão geral do fluxo

Passo 1 — Criar a cobrança

Parâmetros importantes

Passo 2 — Exibir o QR Code

Passo 3 — Receber o webhook

Passo 4 — Consultar o status (opcional)

Quando considerar o pagamento confirmado

Devoluções (refund-in)

Referências