Most payment specs I've reviewed describe the happy path in three pages and the failure behavior in one sentence: "retry on error."
That sentence is where 80% of the production incidents come from.
A payment workflow spec earns its keep by naming — category by category — exactly what the system does when the card network, the issuer, or the customer refuses to cooperate. Here's the structure I use.
Start with a failure taxonomy, not a flowchart
Before drawing a single box, force the spec to answer one question: what are the categories of failure this workflow can produce? I insist on five, because collapsing them into "error" is what creates the mess:
