Skip to main content

​
Papel (para o integrador)

Você não implementa nem chama, em nome do seu sistema, os endpoints de entrada de webhooks abaixo. Eles explicam como a plataforma consome eventos do parceiro e por que a latência e reordenação existem. Úteis para depurar com suporte e entender a causa raiz de atraso vs. o webhook que você recebe (clearpago → comerciante).
MétodoCaminho (clearpago)
POST/api/webhooks/pix/cash-in
POST/api/webhooks/pix/cash-out

​
Autenticação (inbound — parceiro → clearpago)

  • HMAC-SHA256: X-Fire-Signature: sha256=<hex> calculado sobre o body; segredo compartilhado.
  • Timestamp: X-Fire-Timestamp (anti-replay; janela de minutos na descrição de origem).
  • Alternativa: API key estática em header (X-Api-Key ou Authorization) conforme a configuração de ambiente/parceiro.

​
Tratamento interno (visível nas consequências)

  1. Resposta HTTP 200 rápida ao parceiro.
  2. Persistência e fila (ex.: SQS) assíncrona.
  3. Worker aplica máquina de estados, ledger e outbox e notificação ao comerciante.
Idempotência (lado clearpago): duplicatas detectadas (hash / constraints) e descartadas com segurança.

​
Mapeamento de eventos (parceiro)

​
POST /api/webhooks/pix/cash-in

eventEfeito (origem)
CashInAtualiza cash-in (CONFIRMED do parceiro → PAID no domínio, falhas → FAILED, etc.)
CashInReversalAtualiza o refund-in vinculado a transactionId / externalId do estorno
TODO: tabela completa de status CashIn — ver apêndice de payloads (parceiro).

​
POST /api/webhooks/pix/cash-out

eventEfeito (origem)
CashOutConfirma ou falha o envio
CashOutReversalMarca cash-out REVERSED, grava reversão e crédito
Mapeamento resumido de status do webhook: CONFIRMED → CONFIRMED interno; FAILED e afins → FAILED.

​
Payloads (referência)

Apêndice e exemplos (JSON) — estes corpos vão para a clearpago, não para o comerciante.

​
Relação com seu webhook (comerciante)

A sua URL registrada com POST /webhook recebe outro formato assinado. Canais distintos, contratos distintos.