Paystate — Declarative Payment State Machine

"decline" demo profile silently approves instead

This is the demo bank/UPI simulator, so nothing real is at stake -- but imagine it wasn't a demo. simulator_profile: "decline" exists so QA, demos, and integration tests can deterministically prove the created -> failed path works. If it silently approves instead, every test and demo that relies on it to exercise the decline branch is actually testing nothing -- a false green across the board. In a real issuer integration this exact class of bug (a response-code mapping inverted) is how a "payment declined" webhook ends up crediting an order that was never actually paid for.

capture/refund guard lets a ₹0 amount through

positiveAmountGuard is the one guard standing between "capture"/"refund" and a payment that has no real money attached to it. If it lets amount_minor = 0 through, a captured payment with zero value becomes a valid, terminal-adjacent state in the ledger -- invisible in most revenue dashboards (₹0 doesn't move any totals) but very visible to finance during reconciliation, and a clean way for a data-quality bug elsewhere to slip a "successful" payment into the system that represents no actual transaction.

TIMEOUT_SWEEP_BATCH_SIZE is silently ignored

An operator tuning the timeout sweeper's batch size under load (e.g. raising it because timeouts are backing up) sets TIMEOUT_SWEEP_BATCH_SIZE in their deployment config and sees... no change at all, because Load() is reading a differently-spelled env var name and always falls back to the default of 20. There's no error, no warning -- the setting is just silently discarded. This is exactly the kind of bug that costs an on-call engineer an hour of "I set it, why isn't it working?!" before anyone thinks to grep the source for the literal env var name.

Add Machine.IsTerminal(name string) bool

pkg/statemachine.Machine already exposes State(name) (State, bool), which returns a full State struct (Name, Terminal, Failure) plus an ok bool. Any caller that only wants to know "is this state terminal?" has to call State, check ok, then check .Terminal -- three steps for a one-fact question. This is a small ergonomic gap in the reusable library itself.

GET /v1/payments?state= filter

Support and ops staff investigating "why are so many payments failing" need to filter by state without pulling every payment and filtering client-side. GET /v1/payments always returns the 100 most recently created payments, full stop, and the state-filtered route currently 500s.

captured_at/settled_at are swapped when reading a payment back

captured_at and settled_at are exactly the kind of timestamps finance and support pull for "how long did settlement take" reporting and for answering a merchant's "why hasn't my money arrived" ticket. If they're swapped on every single read, every report built on them is silently wrong -- not crashing, not erroring, just quietly showing the wrong timeline for every payment in the system. This is the kind of bug that doesn't get caught until someone cross-checks the API's numbers against the raw database and the two don't match, at which point nobody trusts either.

Outbox payload key typo silently breaks every non-default demo profile

This is a "someone renamed a field on one side and missed a call site" bug -- a classic real production incident shape, especially across a producer/consumer boundary like this one (a JSON payload written by one component, read by another). The visible symptom is severe and confusing: every payment, no matter what simulator_profile was requested at creation, silently gets approved by the demo bank simulator. The "silent" auto-expiry demo and the "decline" demo both stop working project-wide -- not because those features are broken, but because the profile that selects them never reaches the simulator at all.

Outbox rows get one extra retry beyond OUTBOX_MAX_ATTEMPTS

OUTBOX_MAX_ATTEMPTS is the operator's explicit promise to a downstream integration partner (the bank/UPI rail) about how many times we'll retry a call before giving up and dead-lettering it for manual review. If the dispatcher silently allows one extra attempt beyond that, a downstream that's rate-limiting or already returning "permanently rejected" gets hit one more time than agreed -- small on its own, but it's exactly the kind of drift that breaks an SLA with a partner who's counting requests on their side.

Sweeper records "fired" and "invalidated" backwards

The payment_timeouts.status column is the audit trail an on-call engineer or a support ticket investigation reaches for to answer "did this payment's timeout actually go off, or did it correctly get skipped because the payment had already moved on?" If that column is backwards, every such investigation gets the exact opposite answer -- "invalidated" when it really fired, "fired" when it was really a stale no-op. It won't break anything functionally, but it will actively mislead anyone who trusts this table, which is worse than having no record at all.

authorize/decline event constants are swapped — breaks the public HTTP contract while internal tests stay green

POST /v1/payments/{id}/events/authorize -- the literal, documented API endpoint every real integration (a merchant's backend, a support tool, a curl command in this very README) calls to authorize a payment -- currently declines it instead. And the reverse: calling .../events/decline authorizes it. This is about as bad as a payment API bug gets: it's not a crash, not a 500, not even an obviously wrong response -- the request succeeds, returns 200, and does the opposite of what was asked. A merchant integration built and tested against this API would ship completely broken, while every one of this project's own Go-level tests keeps passing, because they all refer to payment.EventAuthorize/EventDecline by their symbolic Go names rather than by the literal string a real HTTP client sends.

GET /v1/payments/{id}/timeouts observability endpoint

There is currently no way to see, via the API, whether a payment has a pending timeout scheduled, what state it's for, or when it's due. The only way to answer "is this payment about to auto-expire, and when?" is to query the payment_timeouts table directly. This is genuinely useful observability for exactly the kind of question ("why did this payment expire when it did?") that comes up during an incident.

Add Builder.MustBuild() *Machine

Builder.Build() returns (*Machine, error). Every current caller in this repo (payment.BuildMachine, the library's own tests, the order-fulfillment example) either propagates that error or handles it explicitly -- reasonable for a caller that takes user-configurable durations and can genuinely fail at runtime. But a caller with a fully static, compile-time-fixed table has no real recovery path for a "build error" other than to panic anyway -- except right now they'd have to write that panic themselves.

Chargeback dispute-window guard

The settled -> charged_back transition currently has no guard at all -- any settled payment can be charged back at any time, no matter how long ago it settled. Real card/UPI networks enforce something similar -- disputes have a filing deadline -- and without this guard the payment machine allows a materially unrealistic sequence that a real integration partner would reject.

ApplyEvent returns a payment one version behind reality

The HTTP API's POST /v1/payments/{id}/events/{event} response is the payment record a client sees immediately after acting on it. If its version field is one behind what's actually stored, any client that implements its own "only proceed if nothing else changed" logic against that version will always think it's acting on stale data one step sooner than it actually is -- every follow-up request looks like a conflict from the client's point of view, or worse, race-condition-shaped bugs downstream that are hard to reproduce because the database is fine, only the response body lied.

ResumeStuckProcessing resumes the wrong rows

This function is the crash-recovery safety net documented in the project's own README: "an instance dies while a row is claimed -> ResumeStuckProcessing, called by every replica at startup, requeues any row left processing past a grace window." With the comparison inverted, that safety net does the opposite of its job on both sides at once: it steals rows a healthy, currently-working replica legitimately has in flight (risking a real duplicate bank call under just the wrong timing), and it leaves genuinely crashed rows stuck processing forever -- exactly the "a payment silently gets lost in limbo after a crash" scenario the whole outbox design exists to prevent.

Expose outbox backlog via /readyz

/readyz only ever reports database_ok. If the outbox dispatcher falls behind (say, the bank simulator/rail is slow or the dispatcher goroutine died silently), there's no signal in readiness -- only in the Prometheus paystate_outbox_depth gauge, which most orchestrators don't scrape as a readiness probe.

Reschedule ("snooze") a pending timeout

Once a timeout is scheduled (e.g. the 15-minute auto-void window on an authorized payment), there's no way to extend it short of waiting for it to fire and manually re-authorizing. A support agent who needs to give a merchant "a bit more time" before an auto-void has no lever to pull.

Optimistic-concurrency check silently removed from UpdateState

This is the single mechanism that makes it safe for a webhook confirming a capture and an auto-void timeout to race each other without corrupting data -- the entire "optimistic concurrency" story the README documents as a core guarantee. Without it, whichever of two concurrent writers commits last simply overwrites whichever committed first, silently. In payment terms: a merchant's capture request and an internal auto-void timeout racing at nearly the same instant could both report success, with one of them's effect vanishing without a trace, no error logged anywhere, no 409 Conflict ever returned.

Outbox dispatcher can claim the same due row twice under concurrency

This is the exact "many replicas must not double-fire the same due work" guarantee the README calls out as this project's reason for running two app replicas by default. Without it, two dispatcher replicas polling at the same moment can both claim and dispatch the SAME outbox row -- meaning the bank/UPI rail can receive two genuinely concurrent, redundant calls for what should be a single side effect. A real bank/UPI integration that isn't perfectly idempotent under true concurrent calls would be exposed to a genuine double-charge risk.

Timeout self-invalidation is silently disabled

This is the other headline guarantee from the README, alongside the outbox crash-recovery story: "a timeout must be self-invalidating... the sweeper re-validates current state (and/or version) atomically at claim time." With that check broken, a timeout scheduled against one "generation" of a payment can fire against a later generation that's still in the same state -- e.g. an auto-void timeout firing after some other legitimate event has already moved the payment's version forward, incorrectly voiding an authorization that should have survived. This is exactly the class of bug a payments system cannot silently ship: money (or the promise of it) moving based on stale information.

Idempotency-Key support for POST /v1/payments

POST /v1/payments has no protection against being accidentally called twice for the same logical request (a client's retry after a timeout, a double-tapped "pay" button, a load balancer replaying a request). Every call creates a brand-new payment, full stop -- exactly the kind of gap that turns a network blip into a real double-charge.

GuardRejectedError should carry a human-readable reason

GuardRejectedError.Reason should hold the rejecting guard's error message (e.g. "payment: amount_minor must be positive") so that 422 responses from the HTTP API actually explain why a transition was rejected, not just that it was. Right now that reason is silently discarded, leaving callers and API consumers with a rejection and no explanation.

Dead-letter outbox replay endpoint

Once an outbox row exhausts OUTBOX_MAX_ATTEMPTS and is marked dead, there's no way to give it another shot short of manual database surgery (UPDATE outbox SET status = 'pending', attempts = 0 WHERE id = ...) -- exactly the kind of thing that turns a 2-minute incident response into a "who has prod DB access and is awake right now" scramble.