O que é reconciliação
Reconciliação é o mecanismo da plataforma para resolver o estado de transações cujo resultado não pôde ser confirmado de forma imediata — seja por falha de rede, timeout ou resposta ambígua do BaaS.
Quando o despacho de uma operação retorna uma resposta inconclusiva, a plataforma marca a transação com PROVIDER_RESULT_UNKNOWN e inicia um ciclo de consultas ao BaaS. Se o BaaS responder com clareza, a transação é resolvida automaticamente. Se as tentativas se esgotarem, o estado avança para RECONCILIATION_REQUIRED.
Estados que indicam reconciliação ativa
| Status | Significado | Ação do integrador |
|---|
PROVIDER_RESULT_UNKNOWN | Resposta ambígua do BaaS; reconciliação em andamento | Monitore com GET; não conclua a operação. |
RECONCILIATION_REQUIRED | Tentativas esgotadas sem resultado claro | Escale para suporte; não conclua a operação. |
Nunca trate PROVIDER_RESULT_UNKNOWN ou RECONCILIATION_REQUIRED como PAID, CONFIRMED, FAILED ou qualquer outro estado terminal. A operação ainda pode ser resolvida em qualquer direção.
Como a reconciliação automática funciona
- Transação entra em
PROVIDER_RESULT_UNKNOWN após resposta ambígua.
- Worker de reconciliação consulta o BaaS em intervalos crescentes (backoff).
- Se o BaaS confirmar: transação vai a
PAID / CONFIRMED e notificação é despachada ao comerciante.
- Se o BaaS informar falha: transação vai a
FAILED e reserva é liberada.
- Se o BaaS não responder após N tentativas: transação vai a
RECONCILIATION_REQUIRED.
O que fazer em cada estado
PROVIDER_RESULT_UNKNOWN
- Polling com
GET periodicamente (ex.: a cada 60 segundos por até 15 minutos).
- Aguarde o webhook
pix_cash_out ou pix_cash_in com resultado.
- Não reenvie a operação enquanto o estado for ambíguo.
curl https://api.clearpago.com.br/api/pix/cash-out/{id} \
-H "Authorization: Bearer <seu_api_token>"
RECONCILIATION_REQUIRED
- Escale para suporte com o
id da transação e o X-Correlation-ID.
- Mantenha a operação como “em análise” na sua base.
- Não registre como sucesso ou falha até resolução.
- Informe o usuário final que há uma análise em andamento, se necessário.
Reconciliação pelo integrador
Além da reconciliação automática da plataforma, o integrador deve fazer sua própria reconciliação periódica para garantir consistência entre o sistema interno e a plataforma.
Reconciliação diária recomendada
- Liste as transações do dia com
GET /api/pix/cash-in?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD.
- Compare com os registros internos.
- Para cada divergência:
- Transação na plataforma mas não no sistema interno: verificar se webhook foi perdido.
- Transação no sistema interno com status diferente da plataforma: atualizar pelo dado da plataforma.
- Repita para cash-out, refund e ledger.
Reconciliação do ledger
# Exporte o ledger do período
curl "https://api.clearpago.com.br/api/pix/ledger?start_date=2026-04-01&end_date=2026-04-01&limit=100" \
-H "Authorization: Bearer <seu_api_token>"
Divergências comuns e como resolver
| Divergência | Causa | Resolução |
|---|
Webhook PAID mas GET mostra PENDING | Webhook chegou antes do estado ser persistido (raro) | Aguardar alguns segundos e consultar novamente. |
GET mostra PAID mas webhook não chegou | Webhook perdido (5xx no seu endpoint) | Reconciliar via GET; corrigir endpoint; verificar logs. |
| Valor no ledger diferente do webhook | Tarifa calculada diferente | Consultar GET /api/pix/ledger/{id} para detalhe; fee_amount_cents pode diferir. |
Cash-out CONFIRMED mas sem lançamento no ledger | Atraso de worker | Aguardar alguns minutos; consultar ledger novamente. |
Janelas de tempo orientativas
TODO: confirmar com a equipe de produto os SLAs exatos de reconciliação automática. Os valores abaixo são orientativos:
| Evento | Janela esperada |
|---|
| Cash-in normal (rede estável) | Segundos a 1–2 minutos |
| Cash-out normal (despacho imediato) | Segundos a poucos minutos |
Reconciliação de PROVIDER_RESULT_UNKNOWN | 5–15 minutos (N tentativas com backoff) |
RECONCILIATION_REQUIRED → resolução manual | Variável; abrir ticket de suporte |
Referências
