Skip to main content

​
Por que monitorar

O modelo assíncrono da ClearPago funciona bem em condições normais, mas estados intermediários prolongados, webhooks perdidos e falhas de rede exigem visibilidade ativa. Sem monitoramento, operações presas podem impactar usuários, saldo disponível e relatórios financeiros.

​
O que monitorar

​
Indicadores de saúde (mínimos)

MétricaSinal de alerta
Cash-ins em PENDING há mais de X minutosPossível problema de pagamento ou rede
Cash-outs em DISPATCHED há mais de Y minutosBaaS pode estar lento; verificar reconciliação
Transações em PROVIDER_RESULT_UNKNOWNReconciliação ativa; monitorar resolução
Transações em RECONCILIATION_REQUIREDRequer ação imediata de suporte
Webhooks sem resposta no tempo esperadoPossível problema no seu endpoint ou na entrega
Taxa de verificação de assinatura com falhaPossível rotação de chave ou ataque
TODO: calibrar os valores de X e Y (janelas de alerta) com base na experiência de produção e nos SLAs da plataforma.

​
Indicadores de ledger

MétricaSinal de alerta
Saldo negativo inesperadoDébito sem crédito correspondente; verificar ordem de eventos
Ausência de lançamento após PAIDDelay de worker; monitorar por alguns minutos
Divergência entre soma de webhooks e ledgerPossível evento duplicado ou perdido

​
Queries de monitoramento (exemplos)

​
Cash-ins antigos em PENDING

curl "https://api.clearpago.com.br/api/pix/cash-in?status=PENDING&start_date=2026-04-01&end_date=2026-04-22" \
  -H "Authorization: Bearer <seu_api_token>"
Use start_date e end_date para restringir o período e identificar os mais antigos.

​
Cash-outs em estado ambíguo

curl "https://api.clearpago.com.br/api/pix/cash-out?status=PROVIDER_RESULT_UNKNOWN" \
  -H "Authorization: Bearer <seu_api_token>"

​
Refunds pendentes

curl "https://api.clearpago.com.br/api/pix/refund?status=PENDING&start_date=2026-04-01&end_date=2026-04-22" \
  -H "Authorization: Bearer <seu_api_token>"

​
Divergências entre webhook e GET

Quando o estado do seu sistema difere do retornado pela API:
CenárioCausa provávelAção
GET retorna PAID mas sistema está PENDINGWebhook perdido ou não processadoAtualizar pelo GET; investigar logs do endpoint.
Webhook PAID mas GET retorna PENDINGWebhook chegou antes da persistênciaAguardar 10–30s e consultar novamente.
Webhook e GET discordantes em status terminaisDois eventos de estados diferentesUsar o GET como autoritativo; verificar chave de idempotência.
GET retorna CONFIRMED mas ledger não tem o lançamentoDelay de worker do ledgerAguardar alguns minutos; consultar ledger novamente.
Regra geral: GET /.../{id} é sempre mais atual que o último evento de webhook recebido. Em caso de conflito, confie na consulta direta.

​
Práticas de suporte a incidentes

​
O que coletar antes de abrir um ticket

  1. id da transação (UUID retornado no 201).
  2. externalId que você enviou.
  3. X-Correlation-ID das chamadas relevantes.
  4. Timestamp aproximado da criação e do momento em que o problema foi detectado.
  5. Status atual retornado pelo GET.
  6. Payloads de webhooks recebidos (se houver).
  7. Logs do seu endpoint de webhook para o período.

​
Escalation path

TODO: confirmar o canal de suporte e SLA de resposta para incidentes de produção. Veja Checklist de produção.

​
Alertas recomendados

Configure alertas no seu sistema de observabilidade para:
  • Cash-in em PENDING há mais de 10 minutos após a expiração esperada do QR.
  • Cash-out em DISPATCHED há mais de 15 minutos.
  • Qualquer transação em RECONCILIATION_REQUIRED.
  • Taxa de erro 5xx no seu endpoint de webhook acima de N%.
  • Webhook sem chegada para um cash-in PAID há mais de 5 minutos (se você tiver polling).
  • Divergência de saldo entre seu sistema e o ledger da ClearPago.

​
Referências