Integration reference
Reconciliation state model
States across commerce, provider, and finance planes—and allowed transitions when matchers succeed or fail.
01
Plane states
Each plane maintains its own state machine. Matchers connect planes; they do not collapse them.
| Plane | Example states | Owner |
|---|---|---|
| Commerce | Open, fulfilled, refunded, disputed | Merchant product/support |
| Provider | Pending, Paid, Confirmed, Expired | Integration + operations |
| Finance | Unposted, recognized, posted, adjusted | Finance/treasury |
02
Allowed transitions
Illegal transitions (e.g., finance posted without provider Confirmed when policy requires it) should fail matchers and route to exceptions—not silent fixes.
- 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