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
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.
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
Compare soma de créditos e débitos com o esperado pelo seu sistema financeiro.
Divergências comuns e como resolver
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:
Referências
