Payment states, authorization, retries and reconciliation
Design a payment workflow that distinguishes prepared, authorized, pending, confirmed, failed and unknown outcomes without creating duplicate money movement.
By Afzal AhmedDetailed guide · 2 min reference readingRead in chapters
The question we’ll work through
What should the application say when the payment provider does not answer?
A payment model that protects reservations, records attempts and supports investigation instead of guessing.
Before you begin
Complete Phase 3 and understand transactions, concurrency and reliable background work. This phase remains synthetic.
This guide is part of a phased educational application. Behaviour is labelled as planned, demonstrated or verified. Examples use synthetic data and simulated money; a real-money launch would require separate commercial, legal, security and operational decisions.
The marketplace must distinguish Prepared, Authorized, In Flight or Pending, Confirmed, Failed, Cancelled and Unknown. A request sent to a provider is not proof that money moved. A timeout is not proof that it failed.
Each logical payment gets a stable identity and one or more recorded attempts. Controlled payments require one person to prepare and another authorized person to approve. The reservation remains protected while an outcome is uncertain. A retry checks the current agreement, approval and available capacity again and uses an idempotency key.
Reconciliation is separate
A provider can confirm a payment before the platform matches it to an account statement. Reconciliation therefore has its own state: Unmatched, Matched or Exception, followed by review and resolution. Corrections create linked records and reasons; they do not erase the original event.
Practise, then reflect
Your turn to make the decision
Model a payment that times out after the provider may have accepted it. Decide what the borrower, operator and funding partner see, and explain why an automatic replacement payment is unsafe.
Compare your reasoning with mine
Keep the logical payment identity and reservation, mark the outcome Unknown, record the provider attempt and route it to investigation. A retry requires fresh approval and an idempotency key; it must not silently create a second payment.
Take it one step further
What evidence would allow an operator to resolve an unknown outcome without trusting a dashboard number alone?