Payment gateway architecture: what production fintech actually requires
Every payment integration looks simple until the first production incident. This is the complete architecture for a payment system that keeps the books true: idempotency, state machines, ledger design, reconciliation, and the failure modes that kill trust.
A payment integration at demo quality is two API calls: create payment intent, confirm, done. A payment integration at production quality is a distributed system with eight failure modes and a legal obligation to keep the numbers right. This post is the architecture document we write before building any payment system.
The fundamental law: money is a state machine
Every payment is a state transition, and every transition must be recorded atomically. There is no such thing as a 'maybe paid' order in a correct system — the state is pending, authorized, captured, partially_refunded, fully_refunded, failed, or disputed. Each transition has a source event, an actor, and a timestamp.
// Payment state machine — strict valid transitions
type PaymentState =
| "pending"
| "authorized"
| "captured"
| "partially_refunded"
| "fully_refunded"
| "failed"
| "disputed";
const VALID_TRANSITIONS: Record<PaymentState, PaymentState[]> = {
pending: ["authorized", "failed"],
authorized: ["captured", "failed"],
captured: ["partially_refunded", "fully_refunded", "disputed"],
partially_refunded: ["partially_refunded", "fully_refunded", "disputed"],
fully_refunded: [],
failed: [],
disputed: ["captured", "fully_refunded"],
};Idempotency: the most important header you send
Network requests fail and retries happen. Without idempotency, a retry on a capture call charges the customer twice. Every mutating API call must include an Idempotency-Key — a stable, unique identifier for the logical operation (not the HTTP request).
Double-entry ledger design
The gateway dashboard is not your ledger. Your system must maintain its own double-entry ledger: every capture creates a credit entry in the payment account and a debit entry in the revenue account. Daily automated reconciliation verifies your ledger against gateway settlement reports line-by-line.
The measure of a payment system is not whether it handles the happy path — every system does. It is whether it handles double callbacks, network timeouts mid-capture, and partial refunds reliably.
Field notes authored by the core engineering and systems team at Chimbuk. We build and maintain production Flutter mobile applications, Next.js web architectures, and cloud backends. No recycled marketing theory — only architecture decisions, code patterns, and performance budgets from real production deployments.
Continue Reading
Related Engineering Guides
We architect and build the systems we write about.
From vector search pipelines to high-concurrency payment gateways — schedule a technical discovery call.