Correlation ID
X-Correlation-ID gerado e enviado em todas as requisições à API.Valor do
X-Correlation-ID registrado nos logs junto a cada chamada para rastreabilidade cruzada.event.correlation_id do webhook (quando presente) correlacionado com o log de criação do recurso.Em incidentes:
X-Correlation-ID disponível para envio ao suporte da ClearPago.Logs
Log de criação de cada recurso:
id, externalId, timestamp, status inicial.Log de cada webhook recebido:
event_type, event.id, status, timestamp de chegada.Log do resultado da verificação de assinatura (válida/inválida) — sem logar o conteúdo do header completo.
Log de cada transição de status processada no seu sistema.
Log de cada lançamento no ledger lido (para auditoria de reconciliação).
Dados pessoais (documentos, nomes) não logados em texto claro.
Logs com nível estruturado (JSON) para facilitar buscas e filtros.
Retenção de logs definida: mínimo 90 dias, idealmente 1 ano para auditoria Pix.
Métricas
Taxa de sucesso de cash-in: % de cobranças que chegam a
PAID vs. criadas.Tempo médio de liquidação de cash-in: da criação ao webhook
pix_cash_in com PAID.Taxa de sucesso de cash-out: % de envios que chegam a
CONFIRMED.Tempo médio de confirmação de cash-out: da criação ao webhook
pix_cash_out com CONFIRMED.Webhooks recebidos vs. eventos esperados: detecta entregas perdidas.
Taxa de verificação de assinatura com falha: detecta rotação de chave ou tentativas de replay.
Transações em
PROVIDER_RESULT_UNKNOWN (contagem ao longo do tempo).Transações em
RECONCILIATION_REQUIRED (alerta crítico se > 0).Alertas
Alerta crítico: qualquer transação em
RECONCILIATION_REQUIRED.Alerta de atenção: transação em
PROVIDER_RESULT_UNKNOWN por mais de 15 minutos.Alerta de atenção: cash-in em
PENDING após a data de expiração do QR.Alerta de atenção: taxa de erro 5xx no endpoint de webhook acima de 1%.
Alerta de atenção: certificado TLS do endpoint de webhook com menos de 30 dias para expirar.
Alerta de informação: cash-out
REVERSED recebido (ação financeira necessária).Reconciliação operacional
Processo de reconciliação diária definido: lista de transações vs. registros internos.
Automação de detecção de divergências (status diferente entre plataforma e seu sistema).
Checagem de ledger diária: soma de créditos e débitos coerente com saldo esperado.
Alertas para divergências de saldo acima de um threshold definido.
Rastreabilidade de incidentes
Runbook documentado com os passos para investigar: cash-in não confirmado, webhook perdido, cash-out preso.
Dashboard operacional com visão em tempo real de transações por estado.
Canal de escalonamento para suporte ClearPago documentado e testado.