Skip to main content

​
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

CampoObrigatórioNotas
transaction.valueSimValor em BRL (ex.: 150.75).
transaction.externalIdSimDeve ser único por cobrança. Duplicidade retorna 409.
transaction.expirationTimeNãoValidade em segundos. Se omitido, a plataforma define o padrão.
transaction.generateQrCodeNãotrue para gerar pixCode (EMV) na resposta.
payer.documentNãoCPF/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:
  1. Verificar a assinatura (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.
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çãoAção
Webhook pix_cash_in com status: PAIDLiberar o pedido.
GET /api/pix/cash-in/{id} retorna PAIDConfirmar e liberar.
Status EXPIREDCriar nova cobrança se necessário.
Status FAILEDRegistrar falha, notificar o usuário.
PROVIDER_RESULT_UNKNOWN / RECONCILIATION_REQUIREDAguardar. Não liberar o pedido.

​
Devoluções (refund-in)

Se precisar devolver um recebimento pago, veja Devolver um cash-in.

​
Referências