Payment State Tracking

Overview

Payment State Tracking creates a chronological record of how a payment moved through its lifecycle. The current state is useful for immediate decisions, while the transition history explains when and why the state changed and which external event caused it.

Tracking data can include invoice identifiers, order references, asset and network, transaction hash, block position, confirmations, provider webhook ID, previous and new state, and processing timestamps. These fields support customer support, reconciliation, audit, and incident investigation.

Polling a current status endpoint is not enough for complete tracking because intermediate states and failed transitions can disappear. Systems should retain an append-only event history or audit log and periodically reconcile it with the authoritative provider and Blockchain Monitoring data.

Duplicate and out-of-order events are expected in distributed payment workflows. A tracker should identify events uniquely, preserve the time they occurred and were received, and let the Payment State Machine decide whether a transition remains valid. Arrival order alone should not determine financial state.

Operational metrics derived from tracking include time to payment, confirmation duration, payments stuck in paying, late payments after expiration, refund completion time, and webhook delivery lag. These measurements help improve reliability while keeping customer-facing messages aligned with actual payment evidence.

Tracking should retain both event time and processing time. A blockchain transfer can occur before an outage, be delivered to the application after recovery, and be credited later still. Keeping these clocks separate supports accurate service-level analysis and prevents delayed ingestion from changing the economic date of the payment.