Guide
Reconciliation and confirmations
Reconciliation is where payments become finance truth. Crypto adds confirmation nuance: your policies must map cleanly to lifecycle semantics.
Definitions: Reconciliation · Paid · Confirmed
Conceptual operational diagram for this guide. Not live merchant data or metrics.
01
What is reconciliation in this context?
It is the disciplined mapping from external payment states to internal orders, revenue recognition triggers, and operational workflows—using explicit lifecycle labels rather than informal language.
02
Why do confirmations matter?
Because operational and accounting risk lives in the gap between “we saw funds” and “our policy considers the payment final for settlement purposes.” Infrastructure should make that gap explicit, not hide it.
03
How do teams implement this well?
Define internal state machines with documented transitions, align webhook consumers to those transitions, and document which external state satisfies each internal gate.
Use idempotent updates so retries and out-of-order delivery do not corrupt ledgering.
04
Common mistakes
- Granting entitlements on Paid when your policy requires Confirmed.
- Letting support tooling interpret statuses differently than finance tooling.
- Assuming one confirmation rule fits every enabled rail.
05
Security considerations
Reconciliation pipelines often touch sensitive business data. Keep webhook verification strict and restrict operational tools with normal least-privilege practices.
- Retries are normal. Webhook delivery is at-least-once. Design consumers to tolerate duplicates and out-of-order arrivals where possible.
- Asynchronous by design. Payers, chains, and your servers operate on different clocks. UI and finance should not assume synchronous finality.
- Eventual consistency. API reads, webhooks, and portal views may briefly diverge during transitions. Reconciliation jobs exist to converge truth.
Walkthroughs: /operations