Designing a Payment System State Machine and Status History Table

In modern payment services, the process involves many steps such as order creation, payment initiation, waiting for third‑party callbacks, refunds, and order closure. Relying solely on a simple status field leads to logic confusion, missing orders, and difficult audits.

Why a Payment System Needs a State Machine

1. Handling Business Complexity

The payment flow is a complex chain from order creation to success, failure, refund, or closure, with many intermediate and exceptional states. Simple status management cannot cope with scenarios like delayed callbacks, user‑initiated cancellations, or frequent refunds.

2. Improving Maintainability and Audibility

Maintainability : A state machine clearly maps states to events, providing a precise roadmap for developers and reducing ad‑hoc status changes.

Audibility : Recording every state change satisfies strict regulatory requirements for financial transactions.

3. Ordered Exception Handling

State machines enable systematic handling of exceptions such as lost callbacks, timeout closures, or refund failures, ensuring consistent system state.

Common Payment Statuses

The following status set covers most payment lifecycles and can be customized:

CREATED : Order generated but payment not started.

PENDING : Payment request sent, awaiting result.

PROCESSING : Third‑party reports a processing state.

SUCCESS : Payment confirmed.

FAIL : Payment failed or timed out.

REFUNDING : Refund in progress.

REFUNDED : Refund completed.

CLOSED : Order cancelled before payment.

Typical State Transition Example

The core mechanism determines the next state from the current state and a triggering event. A simplified diagram (image) shows common events and their resulting state changes.

Design of the Status‑Change History Table

A dedicated history table (e.g., payment_status_history or payment_order_history ) records every transition. Example structure:

order_id : Identifier of the order.

from_status / to_status : Previous and new states.

event : Triggering event name (e.g., PaymentSuccess , CloseOrder ).

operator : Who or which system performed the change.

remark : Additional info such as failure reasons or third‑party codes.

create_time : Timestamp of the change.

Implementing the State Machine in a Project

5.1 Hand‑written State Machine

Typical steps:

Query the current order status.

Check whether the intended event is allowed.

If allowed, update the order to the target status.

Insert a row into payment_status_history .

Code snippets (images) illustrate enum definitions for statuses and events, and the mapping logic using if‑else or switch .

5.2 Using Spring StateMachine

Spring StateMachine provides a systematic way to manage complex states, supports hierarchical and parallel state machines, and can automatically write change logs to the database via listeners. It is suitable for highly complex or visualizable workflows, though a hand‑written approach may suffice for simpler needs.

Key Concerns

1. Idempotency

Repeated callbacks must not cause duplicate updates; for example, if the order is already SUCCESS , further success callbacks can be ignored.

2. Exception Scenarios

Lost third‑party callbacks : Periodically poll the payment provider to update stuck PENDING orders.

Timeout closure : Automatically move CREATED or PENDING to CLOSED after a timeout.

Refund failure : Return to SUCCESS and allow a retry.

3. Partial Refunds

When partial refunds are allowed, record refunded amount and remaining refundable amount, and ensure the state machine can handle multiple refund events.

4. Data Consistency

Use database transactions to keep the order table and history table in sync; large‑scale systems may employ message queues or distributed transaction solutions.

5. Reconciliation and Statistics

Leverage the history table for audit trails, issue diagnosis, and statistical analysis such as state dwell times, failure rates, and refund ratios.

Conclusion

By defining core states (CREATED, PENDING, SUCCESS, FAIL, REFUNDING, REFUNDED, CLOSED) and their triggering events, implementing a clear current state + event → next state rule, and persisting every transition in a multi‑row history table, a payment system can achieve high maintainability, auditability, and robustness even under complex or high‑compliance scenarios.