DEV Community: Daniel Isaac

Model the lifecycle as a state machine, not a bag of booleans

Daniel Isaac — Wed, 05 Aug 2026 16:12:18 +0000

Every system I've worked on with a lifecycle started the same way: a few boolean columns. A payment gets is_pending, is_paid, is_failed, is_refunded. A mandate gets is_active, is_cancelled. It feels harmless, until the day you open a row that is somehow both paid and failed, nobody can say how it got there, and the code can't answer the one question you actually need: can I act on this right now?

The trouble with flags is that nothing stops them combining. Four of them describe sixteen states, most of them nonsense, and every bit of code that touches the row is supposed to remember which combinations are real. Something always forgets.

What I do now is replace the flags with one status and an explicit list of legal moves.

type Status = 'PENDING' | 'PROCESSING' | 'PAID' | 'FAILED' | 'REFUNDED'

const LEGAL: Record<Status, Status[]> = {
  PENDING:    ['PROCESSING', 'FAILED'],
  PROCESSING: ['PAID', 'FAILED'],
  PAID:       ['REFUNDED'],
  FAILED:     ['PENDING'],      // a retry
  REFUNDED:   [],              // terminal
}

That alone kills a whole class of bugs. The value is one of five things, never a contradiction, and "can I act on this" becomes a lookup instead of a guess. Every change goes through one guarded function, so an illegal move throws at the boundary where you can see it, instead of quietly writing something wrong.

function transition(entity, next) {
  if (!LEGAL[entity.status].includes(next))
    throw new IllegalTransition(entity.status, next)
  // ... persist the change (see below)
}

The second half is history. If status is a single column you overwrite, every change erases the one before it, and when something goes wrong you have no idea how the row got there. So I write each transition to an append-only log. The mutable status column stays, because the guard needs a fast answer to "where is this now", but it is a cache; the log is the record of how it got there, and the thing I trust if the two ever disagree.

events: (entity_id, from, to, reason, actor, at)

Now the history is something that happened, not a field I can overwrite. I can see when a payment failed and what we tried next, rebuild the state by replaying, and a stuck record shows itself instead of hiding behind a flag nobody checks.

This is the same shape as the exactly-once work I wrote about. The conditional update is just a transition guard in SQL:

update entity set status = 'PAID'
 where id = $1 and status in ('PENDING', 'PROCESSING');

If no row changes, the move wasn't legal from where the record was, which is also exactly how you swallow a duplicate webhook. The state machine and the idempotency guard turn out to be the same idea in two places.

It's a little more structure than a boolean, and I used to think it wasn't worth it. Then I spent enough late nights trying to reconstruct how a record reached a state that should have been impossible. Now I reach for it first, especially when the thing changing state is someone's money.

Exactly-once money movement: surviving retries and duplicate webhooks

Daniel Isaac — Tue, 04 Aug 2026 11:50:13 +0000

Most of my work has been on systems where money moves, and the bugs I learned to fear were never the loud ones. They were quiet. A customer charged twice. A repayment that went through but never got recorded. You rarely see these in a demo. You see them days later, in reconciliation, when the numbers stop agreeing and someone has to work out why.

Two ordinary things cause most of them. Operations fail halfway, so something retries them. And a payment provider only promises to deliver its callback at least once, which in practice means sometimes twice, sometimes minutes late, sometimes out of order. Put those together and the obvious version of a payment handler will, eventually, do the wrong thing.

The first fix everyone reaches for is to check before acting:

if (!alreadyPaid(orderId)) {
  charge(orderId)
  markPaid(orderId)
}

It looks right. It isn't, the moment there is more than one worker or a webhook gets redelivered, and in production there always is. Two callbacks for the same order arrive together, both ask "already paid?", both hear no, both charge. The gap between the check and the write is where the double charge lives. In-memory locks don't help, because they don't reach across processes.

What worked for me was to stop being careful in application code and let the database settle it. Claim a unique key for the operation before you touch the money, and let a unique constraint reject the duplicate.

create table idempotency_keys (
  key         text primary key,      -- e.g. the provider reference
  status      text not null,         -- PENDING | DONE
  response    jsonb,
  created_at  timestamptz default now()
);

const claimed = insertIfAbsent(key)
if (!claimed) return storedResponseFor(key)   // replay, do not re-charge

const result = charge(...)
finalize(key, result)                          // status = DONE, store response
return result

Now two callbacks racing on the same key collide on the primary key. One wins and does the work; the other reads back the stored result and returns it. There's no window between the check and the act, because the check is the act.

One honest edge: if the duplicate arrives while the first call is still charging, the key exists but the result isn't stored yet. For a webhook that is fine, the first call is already doing the work, so you acknowledge the duplicate and move on. For a caller waiting on an answer, return a "still processing, retry" instead of an empty result. And if the process dies between charging and storing the result, the money moved but the key never got marked done, the one gap idempotency can't close on its own, which is what the reconciliation job is for.

For a status change the same idea is even smaller. Make the update conditional:

update payments
   set status = 'PAID'
 where id = $1
   and status in ('PENDING', 'PROCESSING');

If no row changed, someone already moved it, and you quietly do nothing.

A few things I got wrong before I got them right. The key has to be stable across retries, the provider's transaction reference, not a timestamp. Store the response, not just the fact it happened, so a duplicate gets the same answer the first call did. And keep a reconciliation job as a backstop, because idempotency can't help with the callback you never received.

I came to engineering from law, and the habit that carried over is looking for the edge case that bites later. With money, that edge case is almost always right here: two callbacks in the same millisecond, a retry mid-write. It isn't the interesting part of the work. It's most of the work.