Payment State Version

Overview

How it works

Payment State Version is a monotonic or otherwise controlled version value that identifies which revision of a payment object’s state a record, event, update, or decision represents. Its boundary with Payment State Persistence must remain explicit so related records do not collapse into one status. The record should retain payment ID, state version, previous version, transition, command or event ID, writer, timestamp, schema and software versions, and conflict result. When Payment Processing Stage is involved, the link must be auditable so operators can decide whether retry, repair, return, rerouting, or adjustment is safe.

Important risks include lost updates, out-of-order events, duplicate application, stale writes, inconsistent version schemes, integer overflow assumptions, and consumers ignoring version gaps. Useful measures include write conflicts, stale-update rejection, version-gap rate, duplicate-event suppression, consumer lag by version, and unexplained version resets. Post-incident findings should update controls and runbooks before the same failure recurs.

What matters in practice

Versioning gives each payment-state update an ordered revision, enabling concurrent workers to detect stale writes and clients to distinguish newer from older observations. A compare-and-swap update can require the current version to match the expected one. Versions may be monotonic database counters, stream offsets or well-defined event sequence numbers; timestamps alone can be ambiguous under clock skew. The record must also identify which business rule version interpreted the evidence. A consumer should not accept a lower version simply because the corresponding webhook arrived later.

Related glossary concepts

Payment Notification Event; Payment State Persistence; Payment Processing Stage