Pending, confirmed, and reorganized: a payment’s changing status

Put the observer in the sentence

“Your payment is pending” sounds universal. A more precise sentence is “This wallet’s backend knows about the transaction, and has not observed it in a block on its active chain.”

That extra context matters. A second backend may not have the transaction. One node’s mempool entry is not a public guarantee. A wallet interface may also group different internal conditions under the same label.

When the transaction enters a block that the observer accepts in its active chain, it has one confirmation. Each later block adds another. The count is not a measure of how many nodes clicked an approval button.

A fictional timeline

Imagine a payment in block 800 on a miniature chain. When 800 is the tip, it has one confirmation. With tip 801, it has two. With tip 803, it has four:

confirmations = tip height − inclusion height + 1
              = 803 − 800 + 1 = 4

This equation assumes that the inclusion block remains on the active chain. Height alone is not enough: two competing blocks can have the same height. A real integration tracks the block identity and chain context as well as a number.

What a reorganization changes

Now imagine the observer learns of a different valid branch with more accumulated work and switches to it. If the payment’s inclusion block is disconnected, the earlier count no longer describes its current position.

The payment might appear in the replacement branch, remain unconfirmed and eligible for a local mempool, conflict with a spend in the new history, or have another status under current rules. “A reorg sends every transaction back to pending” is too strong.

For a shop, this is why technical observations and fulfillment decisions need separate fields. The shop may adopt a policy for when it releases goods, but the policy does not modify the chain’s properties. A merchant’s label “settled” should be understood in the context of its risk and provider settings.

More confirmations generally make a history reversal harder under the relevant assumptions, but no fixed count is a universal guarantee for every payment, adversary, or business. Nor is there an unconditional clock promising when the next block arrives. Avoid translating a confirmation target into a guaranteed delivery time.

Build a truthful status message

Take this fictional record:

observed transaction: demo-payment-A
active-chain inclusion: block 800-A
active tip height: 803

Expected display: “4 confirmations on the observed active chain.” Now replace block 800-A with a competing block 800-B that does not contain the payment. You cannot simply keep subtracting heights and display four. First re-establish whether and where the transaction appears in the new chain.

Write three separate fields on paper: transaction observation, confirmation evidence, and business decision. Populate the last with “hold shipment” or “release shipment” according to a fictional policy. The exercise succeeds when changing one field does not silently rewrite the meaning of the others.