Anatomy of a failed transaction
Most “failed” transactions are not failed. The four calls behind one tap, why transactions fail, the reference that keeps one tap one purchase, and what “pending” really means.
The diagrams show typical practice from my own experience, simplified. They are not any company’s internal process.
Most "failed" transactions are not failed
In a digital product chain, "failed" is only one of several outcomes, and often it is not the first. What the customer sees as an error can be a decline, a delay, or a purchase that actually went through.
- Success
The final status says the product was delivered.
- Failed
A clear answer says it was declined.
- No answer yet
The hard one. Not failed, not succeeded.
Read the full section
The customer sees one result on one screen. Behind it, the platform is having a short conversation with the tier above it, and that conversation can end in three ways: success, failure, or no answer yet.
The third one is the hard one. Most of the craft in running a PPOB platform is in how it is handled.
Four calls, not one
A purchase is up to four calls, not one: inquiry, payment, response (a callback), and, when something goes wrong in between, advice.
An inquiry is not needed for every product.
Read the full section
An *inquiry* checks the details before any money moves. For a bill it confirms what is owed. For many prepaid products it is not needed.
A *payment submits the order. A response*, often delivered as a callback, brings back the final status, sometimes at once and sometimes later.
An *advice* is used when the answer did not arrive, for example after a timeout. Instead of guessing, the platform asks again for the status of the same transaction.
Why transactions fail
The usual causes are a timeout, a provider that is down, a wrong destination number and insufficient balance. They can look alike on a screen, but they do not end the same way.
Pick a cause to see what the system sees and what happens next.
- What the system sees
- A clear answer: the destination is not valid.
- Status
- Failed, at once
- Money
- Nothing moves.
- What happens next
- The customer corrects the number and tries again.
Read the full section
Some causes produce a clear answer. A wrong destination number or an insufficient balance is declined, and the transaction fails at once. Nothing has to be investigated.
Others produce silence. A timeout, or a provider that does not answer, leaves the platform without a final status. That is why "pending" exists, and why it is not the same as failure.
Pick a cause below to see what the system sees and what happens next. It is a simplified picture of typical practice.
One reference per request
Every request carries a unique transaction_id, used across digital and PPOB transactions. It is how a repeat is recognised and how the tiers match their records afterwards.
Read the full section
I keep this at the level of the idea. A customer who taps twice, or a platform that asks again after a timeout, sends a request that refers to the same transaction. With a reference, it can be recognised as a repeat instead of being processed as a second purchase.
The same reference is what the tiers use to match records when they reconcile.
Pending, suspect, reconciled
Pending is not failed. After about an hour a pending transaction is treated as suspect, and the tiers reconcile, automatically and manually, within a day at most.
Read the full section
Reconciliation is mostly automatic: the tiers compare their records and settle what matches. What automation cannot settle is reconciled manually. In my experience this finishes within a day at most.
Providers also have maintenance windows, which affect every kind of product. A delay in one of them can look like a failure when it is not.
The platform and the deposit side run around the clock. The exception is the cut-off hours that a provider sets for itself.
What newcomers get wrong
The mistakes I see most are less about technology than about patience, discipline and presence.
- Impatience
- Greed
- Thin technical understanding
- Overlooking regulation
- A price war from day one
- No community or market presence
Read the full section
Newcomers are often impatient and greedy. They have a thin understanding of the technology, they overlook regulation, they start a price war from day one, and they do not build a community or a market presence in their own region.
The same discipline applies to who joins the chain. Merchants are checked online with eKYC, or manually with KYC or KYB. The fraud attempts I see most are the use of other people's documents and social engineering.
What to take from it
Design for the unknown state, give every request a reference, and reconcile every day.
Read the full section
If you build the product, treat "processing" as a real status and show it honestly. A customer who knows the transaction is still being processed does not pay twice.
If you run operations, keep a unique reference for every request, treat pending as a first-class status, and reconcile daily.
Sources and notes
Typical practice from my own experience, not any company's internal process. The simulator is a simplified illustration.
- A related public example: Snapcart's PPOB API documentation classifies a timeout as an in-progress status and uses callbacks and polling.
- The full chain, tier by tier, is in the deep explainer.