Design Crypto Payment Gateway

Problem Statement: Merchant Crypto Checkout Gateway

A crypto payment gateway lets a merchant accept crypto at checkout and receive predictable settlement — the shopper pays BTC/ETH/USDC against a hosted invoice, the gateway detects the on-chain payment, waits for confirmations, and settles the merchant in fiat or USDC. This is BitPay and Coinbase Commerce: hosted checkout, a locked FX quote, a unique deposit address per invoice, a per-chain confirmation policy, and merchant payout.

The defining truth: the hard problem is the FX quote, not blockchain TPS. BitPay and Coinbase Commerce postmortems are about quote expiry and volatility, not throughput. When a shopper is quoted '0.0042 BTC = $200' and takes 20 minutes to pay while BTC moves, someone eats the difference. So the central questions are how long the quote is locked, who bears the volatility between payment and fiat settlement (the liability boundary), and what happens on under/overpayment — not how many TPS the chain does.

The core flow. Lock an FX quote (oracle median, with a staleness gate so you don't quote during an exchange-API outage) → mint a unique deposit address per invoice (so payments attribute unambiguously) → a per-chain watcher detects the inbound tx → confirmations accrue under a per-chain policy (ETH ~12 blocks, BTC 2–6 depending on ticket size) → AML-screen the inbound tx before crediting → credit the merchant in a double-entry ledger → sweep deposits to an omnibus treasury → batch fiat/USDC settlement to the merchant.

The money-correctness invariants. A double-entry ledger ties invoice_paid → treasury_inbound → merchant_payout_outbound (every credit has a matching debit); overpayment creates an explicit liability bucket (a surplus owed back, never a silent windfall); underpayment (a ~2% BTC underpay from wallet fee-estimation is common) is an explicit partial-pay state, never silently waved through; and status transitions are monotonic so a reorg replay never moves an invoice backward.

The consistency model, stated plainly. Invoice status is CP (strongly consistent in PostgreSQL) — the merchant-facing source of truth; the chain index is AP (eventually consistent, with repair jobs). A shaky chain read never corrupts the authoritative invoice state.

Scale and SLOs to anchor on: confirm p95 < 8 min on ETH, < 45 min on BTC during congestion; fiat settlement batched every ~15 min with an FX hedge; sweep to omnibus when a deposit address exceeds ~$2,500; per-chain watcher isolation (a Solana outage must not stall BTC confirmations); at-least-once webhooks (merchants dedupe on invoice_id + event_id); 7-year audit retention. The engineering is exactly-once payment accounting against eventually-consistent chains, honest volatility handling, and a settlement pipeline that never double-credits.