Skip to main content

​
Cash-in (recebimento)

  1. POST /api/pix/cash-in → geralmente PENDING e eventualmente pixCode (EMV).
  2. O pagador liquida no parceiro.
  3. O parceiro chama a clearpago em POST /api/webhooks/pix/cash-in (você não expõe este endpoint). Workers aplicam estados, ledger e outbox de notificação.
  4. Seu endpoint recebe POST com event_type: pix_cash_in (assinado). Consulte o detalhe com GET /api/pix/cash-in/{id} em caso de dúvida.
  5. Trate PAID como sucesso financeiro usual para “liberar” o pedido; respeitando a política interna (ver status).

​
Cash-out (por chave ou QR)

  1. POST /api/pix/cash-out ou POST /api/pix/cash-out-qrcode → reserva e encadeamento (outbox/despacho).
  2. O despacho fala com o BaaS; respostas ambíguas (timeout, 5xx, EOF) podem levar a reconciliação sem liberar reserva indevidamente.
  3. Webhook do parceiro em POST /api/webhooks/pix/cash-out (interno) atualiza estados; seu sistema recebe pix_cash_out quando aplicável.
  4. Confirmação de transferência: status terminal típico CONFIRMED no domínio documentado, após o pipeline (incluindo DISPATCHED conforme o caso). Veja envio por chave.

​
Refund-in (devolução do recebimento)

  1. Sobre cash-in PAID, POST /api/pix/refund-in/{id} com {id} = UUID do cash-in.
  2. Prazo: até 89 dias após o recebimento. Parciais múltiplos permitidos; somas competem por teto.
  3. Webhook de parceiro com CashInReversal amarra o resultado; seu comerciante recebe pix_cash_in_reversal com semântica de IDs específica (ver referência de webhooks).

​
Reversão de cash-out (devolução pelo destinatário)

  1. Ocorre após envio CONFIRMED quando o parceiro emite CashOutReversal.
  2. O cash-out vai a REVERSED; há crédito no ledger.
  3. Seu comerciante recebe pix_cash_out_reversal com event.id = UUID do cash-out; monitore value_cents (fallback documentado no código de origem se metadados incompletos). Ver guia.

​
Como “os eventos chegam”

  • BaaS → clearpago: webhooks internos (HMAC/timestamp, etc.); assíncrono.
  • clearpago → comerciante: Digital-Signature (ECDSA) no corpo JSON; responda 2xx rápido.
  • Reconciliação: preenche lacunas quando webhooks atrasam ou a rede foi ambígua.

​
O que o sistema integrador deve fazer

  • Persistir id e externalId cedo.
  • Tornar handlers de webhook idempotentes (mesmo evento + mesma transição pode repetir).
  • Monitorar estados não terminais antigos e alinhar com reconciliação operacional.