Skip to main content

​
O que é reconciliação

Reconciliação é o processo de resolver estados inconclusivos de transações consultando o BaaS diretamente. Ela ocorre de forma automática pela plataforma em estados como PROVIDER_RESULT_UNKNOWN e RECONCILIATION_REQUIRED, mas também é relevante para o integrador no monitoramento operacional.

​
Quando a reconciliação é necessária

SituaçãoCausa
PROVIDER_RESULT_UNKNOWNResposta ambígua do BaaS (timeout, 5xx, EOF) na chamada de despacho.
RECONCILIATION_REQUIREDTentativas automáticas esgotadas sem resultado claro.
Webhook não recebidoEntrega falhou; o estado real pode ser diferente do que você persistiu.
Divergência entre webhook e GETReentrega antiga ou processamento fora de ordem.

​
O que fazer em cada situação

​
1. Status PROVIDER_RESULT_UNKNOWN

A plataforma está consultando o BaaS periodicamente. Não aja antes do resultado. 
# Consulte periodicamente (ex.: a cada 30 segundos por até 5 minutos)
curl https://api.clearpago.com.br/api/pix/cash-out/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer <seu_api_token>"
  • Se transicionar para CONFIRMED: processe como sucesso.
  • Se transicionar para FAILED: processe como falha; reserva foi liberada.
  • Se permanecer por mais de 10–15 minutos: acione suporte.

​
2. Status RECONCILIATION_REQUIRED

As tentativas automáticas foram esgotadas. Ação humana ou escalonamento é necessário.
  • Acione o canal de suporte com o id da transação e o X-Correlation-ID.
  • Não conclua a operação (pago/falhou) no seu sistema até resolução.
  • Guarde o estado como “em análise” internamente.

​
3. Webhook não recebido no tempo esperado

Após o tempo máximo esperado (ex.: 5–10 minutos para cash-in), consulte diretamente: 
curl https://api.clearpago.com.br/api/pix/cash-in/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <seu_api_token>"
  • Se PAID: o pagamento foi confirmado mesmo sem webhook; processe localmente.
  • Se PENDING: ainda aguardando; defina um novo timeout e monitore.
  • Se EXPIRED ou FAILED: encerre o fluxo conforme a regra de negócio.

​
4. Divergência entre webhook e GET

Pode ocorrer quando um webhook atrasado chega com um status “anterior” ao que já está na base. Regra: o estado obtido via GET /.../{id} é autoritativo. Atualize conforme o GET e descarte transições para estados “anteriores”. 
webhook: PENDING → ignorar se GET já mostra PAID
webhook: PAID → processar se GET confirma PAID

​
Fluxo de monitoramento operacional

Para manter a saúde da integração:

​
Boas práticas

  • Defina timeouts por tipo de operação. Cash-in costuma ser mais rápido que cash-out; calibre os tempos de espera.
  • Use X-Correlation-ID. Em escalonamento de suporte, o correlation ID facilita a busca nos logs da plataforma.
  • Monitore a lista de transações GET /api/pix/cash-in?status=PENDING&start_date=... para identificar transações antigas sem resolução.
  • Não reenvie cash-out automaticamente sem confirmar que o anterior foi FAILED — risco de duplicidade financeira.
  • Registre todos os estados intermediários na sua base para auditoria.

​
Listar transações por estado

​
Cash-ins pendentes há mais de 1 hora

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

​
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>"

​
Referências