Playbook
Settlement operations checklist
Daily and incident-oriented settlement controls: detection vs confirmation discipline, checkpoint review, and drift signals.
01
Objective
Run recurring settlement operations with explicit separation between detection, policy confirmation, and treasury recognition—surfacing drift before period close.
02
Prerequisites
- Lifecycle enums documented per environment.
- Settlement checkpoints configured with owners.
- Dashboards or reports for stuck states (Paid without Confirmed, etc.).
03
Operational signals
- Growing count of manual lifecycle overrides.
- Increasing age of payments in intermediate states.
- Mismatch between provider plane totals and commerce fulfilled orders.
04
Decision points
- Which states auto-advance versus require human review.
- When to open exception queue versus wait for confirmations.
- Whether to throttle fulfillment during rail instability.
05
Escalation paths
- Operations → finance for recognition policy exceptions.
- Engineering → provider support for detection gaps.
- Treasury → compliance for high-value holds.
06
Failure modes
- Treating explorer visibility as Confirmed for all SKUs.
- Skipping checkpoint review during high volume.
- Collapsing async settlement into single paid flag.
07
Recovery patterns
- Run settlement checkpoint audit on affected payment_ids.
- Route ambiguous cases to exception taxonomy classes.
- Communicate customer-visible delays with policy-backed language.
- Update checkpoint config from drift root cause.
- 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