Flair BuchiMiracle Okonkwo

WritingMarch 2026

Why Payment Systems Need a Source of Truth

A payment can look successful long before a financial system should treat it as complete. Signals are not the same thing as financial truth.


A payment can look successful long before a financial system should treat it as complete.

A customer can pay. A blockchain observer can detect the transaction. A provider can return a successful response. A webhook can arrive. A checkout session can move forward.

And yet the merchant balance may still need to remain unchanged.

This is one of the less obvious problems in payment infrastructure: the system receives many signals about what happened, but those signals are not necessarily the same thing as financial truth.

The more providers, rails, webhooks, wallets, and asynchronous processes a payment touches, the more important that distinction becomes. Building Xpend B2B made that concrete.

A payment intent is not a payment

One useful way to think about a payment intent is as a durable statement of expectation.

It says what the merchant is trying to collect, under what conditions, for which environment, and where the resulting settlement should go.

It gives the rest of the system something stable to coordinate around. But it should not be responsible for answering every question about the payment.

A payment intent can tell us that a merchant expected a particular asset or amount. It cannot, by itself, prove that the money arrived.

Payment processing is asynchronous. The intent can exist before a customer pays. A deposit can be detected before it is confirmed. A provider can accept an operation before the final result is known.

If the system treats one mutable status field as the complete history of the transaction, every late webhook or retry becomes an argument over what that field should say.

The better approach is to separate coordination state from financial evidence. The intent describes what the system is trying to accomplish. The evidence describes what has actually happened.

Webhooks are evidence, not truth

Webhooks are incredibly useful. They let external systems tell you that something changed without requiring your application to constantly poll them.

But a webhook is still an external event. It can arrive twice. It can arrive late. It can arrive out of order. It can describe an intermediate state. It can even arrive after your own system has already processed the underlying event through another path.

That makes a webhook a poor place to directly mutate financial truth.

A safer pattern is to treat external events as inputs to an inbox. The event is identified, deduplicated, normalized, and processed by the application's own state machine.

That creates an important boundary: The provider reports an event. The application decides what that event means.

This also makes retries much less dangerous. If the same event arrives twice, the desired outcome isn't to somehow guarantee that the provider never sends it twice. The desired outcome is that processing it twice produces the same financial result as processing it once.

Idempotency becomes more valuable than the illusion of exactly-once delivery.

Confirmation is not the same as credit

There is another boundary that becomes important with blockchain payments.

A transaction being detected does not necessarily mean it should become merchant balance. Detection tells you that something was observed. Confirmation provides stronger evidence that the deposit is actually established on the chain.

Even then, confirmation may not be enough.

A payment can be confirmed but still fail the application's funding or economic requirements. An amount can be below the acceptable minimum. The payment can be associated with the wrong expectation. Other business rules may prevent it from becoming spendable funds.

So the pipeline should be able to express these states independently: detected → confirmed → eligible → credited

Those are not four names for the same thing. They represent four different questions.

Was something seen? Has the underlying event reached the required level of confirmation? Does it satisfy the rules for this payment? Should the merchant's financial position actually change?

Collapsing those questions into a single status makes failures harder to reason about. Keeping them separate makes the system more boring—and boring is exactly what you want around money.

The ledger is where financial consequences become real

Eventually, the system has to answer a simple question:

How much money does this merchant actually have?

That answer should not depend on whichever provider responded most recently. It should come from the application's own financial record.

In our payment systems, the ledger is append-only. Balance projections are derived from that ledger rather than maintained as an independent source of financial truth.

That design changes how failures behave.

A duplicate webhook doesn't create another balance change. A provider timeout doesn't become an invented successful transaction. A retry doesn't need to reconstruct the merchant's balance from a provider dashboard. A corrective operation can be represented as another ledger event rather than silently overwriting history.

The ledger therefore becomes more than an accounting implementation. It becomes the boundary between what the outside world reported and what the application has accepted as a financial consequence.

That boundary is critical.

Provider identity should belong to the operation

There is a related problem when multiple providers can execute the same kind of operation.

Imagine changing the active provider while an existing payment is still moving through the system. If the system looks up the current provider whenever a callback arrives, an old operation can accidentally become associated with a new provider.

That is dangerous.

Provider selection should happen at the point where an operation is created or claimed, and that execution should retain its own identity.

The payment intent represents the merchant's expectation. The execution attempt represents how the system tried to fulfill it. The ledger represents the resulting financial effect.

Those identities can be related without being interchangeable.

This also makes provider switching safer. A new operation can use a different provider without rewriting the meaning of an operation that is already in flight.

The provider can change. The merchant's obligation does not. The financial history does not.

The system should survive disagreement

This is probably the most important consequence of having a source of truth.

Real payment systems will disagree with themselves temporarily.

A provider may say an operation is pending while an internal processor is retrying it. A webhook may arrive after another processing path has already handled the event. A transaction may be confirmed on-chain while the payment is still ineligible for credit. A checkout session may appear complete while settlement is still being finalized.

These aren't necessarily exceptional failures. They are properties of distributed systems.

The goal isn't to make every component agree instantly. The goal is to make disagreement recoverable without corrupting financial truth.

That requires clear boundaries.

Payment intents coordinate expectations. Providers execute operations. Webhooks provide external observations. Confirmation establishes evidence. Business gates determine eligibility. The ledger records financial consequences.

Projections and user-facing statuses can then be rebuilt from those underlying facts.

What this changes when things go wrong

The architecture of a payment system is easiest to understand when something goes wrong.

If a webhook is duplicated, idempotency should make the second event boring. If a provider times out, the system should not have to guess whether money moved. If a deposit is detected but never becomes eligible, the observation should remain distinct from the balance. If a provider changes, an existing execution should still have an identifiable owner. If a balance projection becomes inconsistent, it should be possible to rebuild it from the ledger.

These aren't just implementation details. They determine whether the system can recover from the normal messiness of asynchronous money movement without asking an operator to manually decide what the balance should be.

That is the real value of a source of truth. It gives every other component permission to be imperfect.

The boring part is the important part

Payment infrastructure is often described in terms of integrations: which provider, which chain, which checkout, which wallet, which API.

But the harder problem is deciding which of those systems gets to define reality.

The answer should not be the latest webhook. It should not be the current provider. It should not be a checkout status. And it should not be a mutable field that gets rewritten every time another system reports something new.

A payment system becomes much easier to reason about when there is a durable financial record underneath all of those moving parts.

Providers can fail. Webhooks can duplicate. Networks can be asynchronous. Operations can be retried. Providers can be replaced.

The financial history still has to make sense.

The goal isn't to make every component agree instantly. It's to make disagreement recoverable without corrupting financial truth.