Guide
Reconciliation implementation checklist
Use this checklist when designing matchers, exception queues, and period close—not as universal accounting policy.
Definitions: Three-plane reconciliation · Exception queue · Finance reconciliation
Conceptual operational diagram for this guide. Not live merchant data or metrics.
01
Define the three planes
- Commerce plane: orders, invoices, subscriptions with stable merchant references.
- Provider plane: payment_id lifecycle from API and verified webhooks.
- Finance plane: ledger/treasury postings under your recognition policy.
- Document mapping tables between plane identifiers—not assumed 1:1 joins.
02
Matcher and tolerance rules
- Amount tolerances per asset and rail—explicit, not tribal knowledge.
- Reference matching rules for memos, order ids, and partial payments.
- Timing windows for async settlement before raising timing-skew exceptions.
- Auto-resolve only where taxonomy and finance policy allow it.
03
Exception queue ownership
Route failed matchers to named exception classes with owners (support, treasury, engineering, finance). Require resolution codes and payment_id references—avoid free-text-only closes.
04
Period close ceremony
- Re-run matchers for the close window with frozen tolerances.
- Review aging exceptions by class—not only total unmatched value.
- Finance sign-off references provider event evidence, not explorer screenshots alone.
- Record drift metrics if plane totals diverge beyond thresholds.
- 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