Part 1 \u2014 Gateway architecture, PCI-DSS, tokenization, idempotent checkout, and SAGA-based refunds.<\/p>\n\n<\/div><\/div>\n\n\n\n
By Alera Infotech Engineering<\/strong> | October 2025<\/p>\n\n\n\n Payments systems live at the intersection of throughput, irreversibility, and regulation<\/strong>. This guide walks Staff-level engineers through building a fault-tolerant, PCI-aware eCommerce payments platform<\/strong> using Java + Spring Boot + Kafka + PostgreSQL (AWS)<\/strong>. We focus on determinism<\/em> (exactly-once outcomes), auditability<\/em>, and evolution<\/em> (how the system scales and changes safely).<\/p>\n\n\n\n Checkout Service \u2192 Payments API \u2192 Orchestrator \u2192 Gateway Adapters (Stripe\/Adyen\/Razorpay\/etc.) \u2192 Risk\/Fraud \u2192 Ledger \u2192 Webhooks & Notifications \u2192 Reconciliation<\/strong>. Kafka connects services; Outbox pattern guarantees exactly-once event publication.<\/p>\n\n\n\n Goal:<\/strong> keep Primary Account Number (PAN) out of your environment. Let the Payment Service Provider (PSP) or a PCI vault handle card data. Your systems operate on tokens<\/em>.<\/p>\n\n\n\n Design the PCI boundary so that a breach of your app does not<\/em> disclose PAN. This is the single highest-leverage architectural decision in eCommerce.<\/p>\n<\/blockquote>\n\n\n\n Idempotency ensures retries (client\/network) don\u2019t double-charge. We rely on a client-supplied Notes:<\/strong> Persist the response JSON (plus request hash) under The Orchestrator implements the payment state machine<\/strong> and calls Gateway Adapters. Adapters map your internal DTOs to each PSP\u2019s API, handle errors, and normalize responses (auth code, AVS\/CVV results, 3DS status).<\/p>\n\n\n\n The Outbox<\/em> write occurs in the same DB transaction as the authorization record. A background publisher emits the event to Kafka after commit, ensuring exactly-once publication.<\/p>\n\n\n\n Refunds span multiple systems (your DB, PSP, notifications). Implement a SAGA<\/strong> with compensations: if the PSP call succeeds but notification fails, you must still record the refund and schedule retries \u2014 do not roll back the bank.<\/p>\n\n\n\n SAGA rule: never<\/em> attempt to \u201cundo\u201d a bank transaction by deleting rows. Use compensating entries<\/strong> in the ledger. Money moves are append-only.<\/p>\n<\/blockquote>\n\n\n\n The ledger is the source of truth<\/em> for money. Use double-entry<\/strong> (debits\/credits) with append-only<\/em> entries. Never update historical rows; post adjustments. Keep transaction<\/strong> and entry<\/strong> tables separate.<\/p>\n\n\n\n Invariants:<\/strong> (1) Entries for a transaction must balance to zero; (2) No delete\/update of entries; (3) Currency must match across postings; (4) Referential integrity to payments\/refunds.<\/p>\n\n\n\n The ledger protects you when gateways misbehave. If settlement files disagree, you can prove exactly<\/em> what you believe about the money and why.<\/p><\/blockquote>\n\n\n\n Each PSP provides daily settlement\/reconciliation files (CSV\/JSON\/SFTP). A reconciliation job ingests the file, normalizes rows, and matches them to your Real-time rules:<\/strong> velocity per card\/email\/IP, BIN risk, country mismatch; Async ML:<\/strong> feature store + gRPC model. Log reason codes<\/em> for every decision to support disputes.<\/p>\n\n\n\n Outbox:<\/strong> events written in-transaction; DLQ:<\/strong> permanent processing errors; Replay:<\/strong> reconcile by event idempotency keys. Expose DLQ age & depth alarms.<\/p>\n\n\n\n Assume average request \u2248 2 KB JSON, processing \u2248 300 ms. A single WebFlux instance on a c7g.2xlarge can handle ~300\u2013500 req\/s depending on GC & I\/O. For 10k RPS sustained: ~25\u201335 instances (+ 20 % headroom). Batch workers scale horizontally via Kafka consumer groups.<\/p>\n\n\n\n Design DR so that the same<\/em> idempotency key produces the same<\/em> outcome regardless of region. Determinism beats heroics.<\/p><\/blockquote>\n\n\n \u00a9 2025 Alera Infotech Engineering | Tags: payments, java, spring boot, kafka, pci dss, idempotency, ledger, reconciliation, reliability<\/em><\/p>\n\n","protected":false},"excerpt":{"rendered":" By Alera Infotech Engineering | October 2025 Payments systems live at the intersection of throughput, irreversibility, and regulation. This guide walks Staff-level engineers through building a fault-tolerant, PCI-aware eCommerce payments platform using Java + Spring Boot + Kafka + PostgreSQL (AWS). We focus on determinism (exactly-once outcomes), auditability, and evolution (how the system scales and […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[11],"tags":[],"class_list":["post-1035","post","type-post","status-publish","format-standard","hentry","category-careers"],"_links":{"self":[{"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/posts\/1035","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/comments?post=1035"}],"version-history":[{"count":2,"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/posts\/1035\/revisions"}],"predecessor-version":[{"id":1037,"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/posts\/1035\/revisions\/1037"}],"wp:attachment":[{"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/media?parent=1035"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/categories?post=1035"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.alerainfotech.com\/home\/wp-json\/wp\/v2\/tags?post=1035"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
\n\n\n\n1) Responsibilities at Staff Level (Fintech\/eCommerce)<\/h2>\n\n\n\n
\n
2) System Overview (High-Level Flow)<\/h2>\n\n\n\n
Core Services<\/h3>\n\n\n\n
\n
3) PCI-DSS & Tokenization Boundary<\/h2>\n\n\n\n
\n
card_token<\/code>.<\/li>\n\n\n\n\n
4) Idempotent Checkout API (Spring Boot)<\/h2>\n\n\n\n
Idempotency-Key<\/code> spanning the entire authorization or capture request. Store request\/response hash keyed by the idempotency key.<\/p>\n\n\n\nController + Idempotency Filter (Java)<\/h3>\n\n\n\n
\/\/ build.gradle (snippets)\n\/\/ implementation 'org.springframework.boot:spring-boot-starter-web'\n\/\/ implementation 'org.springframework.boot:spring-boot-starter-validation'\n\/\/ implementation 'org.springframework.kafka:spring-kafka'\n\/\/ implementation 'org.springframework.boot:spring-boot-starter-data-jdbc'\n\/\/ implementation 'org.postgresql:postgresql'\n\n\/\/ IdempotencyFilter.java\n@Component\n@Order(1)\npublic class IdempotencyFilter implements Filter {\n @Autowired IdempotencyStore store; \/\/ e.g., Redis or Postgres\n\n @Override\n public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)\n throws IOException, ServletException {\n HttpServletRequest http = (HttpServletRequest) req;\n HttpServletResponse httpRes = (HttpServletResponse) res;\n String key = http.getHeader(\"Idempotency-Key\");\n if (key == null || key.isBlank()) { chain.doFilter(req, res); return; }\n\n Optional<String> prior = store.getResponse(key);\n if (prior.isPresent()) {\n httpRes.setHeader(\"Idempotency-Replayed\", \"true\");\n httpRes.getWriter().write(prior.get());\n return;\n }\n\n ContentCachingResponseWrapper wrapper = new ContentCachingResponseWrapper(httpRes);\n chain.doFilter(req, wrapper);\n String body = new String(wrapper.getContentAsByteArray(), StandardCharsets.UTF_8);\n store.save(key, body);\n wrapper.copyBodyToResponse();\n }\n}\n\n\/\/ PaymentsController.java\n@RestController\n@RequestMapping(\"\/payments\")\npublic class PaymentsController {\n\n @Autowired PaymentService service;\n\n @PostMapping(\"\/authorize\")\n public ResponseEntity<PaymentAuthResponse> authorize(@Valid @RequestBody PaymentAuthRequest req,\n @RequestHeader(value=\"Idempotency-Key\", required=false) String idemKey) {\n return ResponseEntity.ok(service.authorize(req, idemKey));\n }\n}<\/code><\/pre>\n\n\n\nIdempotency-Key<\/code>. For safety, scope keys to merchantId<\/code> + customerId<\/code>. Expire keys (e.g., 24\u201348h) to bound storage.<\/p>\n\n\n\n5) Orchestration & Gateway Adapters<\/h2>\n\n\n\n
State Machine (Authorize \u2192 Capture \u2192 Settle)<\/h3>\n\n\n\n
\n
Outbox Event After DB Commit<\/h3>\n\n\n\n
@Transactional\npublic PaymentAuthResponse authorize(PaymentAuthRequest r, String idemKey) {\n Payment p = repo.createAuthorized(r); \/\/ authorizations table\n \/\/ call adapter\n GatewayAuthResult g = gatewayAdapter.authorize(r);\n repo.updateWithGateway(p.getId(), g);\n outbox.storeEvent(\"payment.authorized\", p.getId(), g); \/\/ same TX commit\n return PaymentAuthResponse.from(p, g);\n}<\/code><\/pre>\n\n\n\n6) Refunds & Reversals with SAGA<\/h2>\n\n\n\n
Refund Saga Steps<\/h3>\n\n\n\n
\n
refund_requested<\/code> row \u2192 emit refund.requested<\/code>.<\/li>\n\n\n\nrefund()<\/code> (idempotent with Idempotency-Key<\/code>).<\/li>\n\n\n\nrefund_completed<\/code> + ledger entries (negative amount).<\/li>\n\n\n\nrefund.completed<\/code> \u2192 send email\/notification.<\/li>\n\n\n\nledger reversal<\/code> and alert ops.<\/li>\n<\/ul>\n\n\n\npublic void refund(String paymentId, Money amount) {\n Refund r = repo.createRefund(paymentId, amount); \/\/ state = REQUESTED\n try {\n GatewayRefundResult gr = adapter.refund(paymentId, amount, r.getId()); \/\/ pass refund id as idem\n repo.markRefundCompleted(r.getId(), gr);\n ledger.postRefund(paymentId, amount, r.getId()); \/\/ append-only, negative entry\n outbox.storeEvent(\"refund.completed\", r.getId(), gr);\n } catch (GatewayDeclined e) {\n repo.markRefundFailed(r.getId(), e.getCode());\n outbox.storeEvent(\"refund.failed\", r.getId(), Map.of(\"reason\", e.getCode()));\n }\n}<\/code><\/pre>\n\n\n\n\n
\n\n\n\nPart 2 \u2014 Ledger & Reconciliation, Fraud, Observability, SLOs, Scale & DR<\/h2>\n\n<\/div><\/div>\n\n\n\n
7) Ledger: Double-Entry Accounting & Invariants<\/h2>\n\n\n\n
Schema Sketch (PostgreSQL)<\/h3>\n\n\n
-- transactions: logical money movements (auth, capture, refund)\nCREATE TABLE transactions (\n id UUID PRIMARY KEY,\n merchant_id UUID NOT NULL,\n payment_id UUID NOT NULL,\n type TEXT CHECK (type IN ('AUTH','CAPTURE','REFUND','FEE','CHARGEBACK')),\n amount_cents BIGINT NOT NULL,\n currency CHAR(3) NOT NULL,\n created_at TIMESTAMPTZ NOT NULL DEFAULT now(),\n metadata JSONB\n);\n\n-- entries: double-entry postings that must net to zero per transaction\nCREATE TABLE entries (\n id UUID PRIMARY KEY,\n transaction_id UUID REFERENCES transactions(id),\n account TEXT NOT NULL, -- e.g., \"merchant_receivable\", \"psp_payable\", \"fees_income\"\n direction TEXT CHECK (direction IN ('DEBIT','CREDIT')),\n amount_cents BIGINT NOT NULL,\n currency CHAR(3) NOT NULL,\n created_at TIMESTAMPTZ NOT NULL DEFAULT now()\n);\n\n-- invariant: sum(entries.amount with sign) = 0 per transaction\n-- enforce via trigger or periodic assertion + reconciliation job<\/code><\/pre>\n\n\n\nPosting Example (Capture)<\/h3>\n\n\n
\n
8) Reconciliation: Matching PSP Files to Your Ledger<\/h2>\n\n\n\n
transactions<\/code> and entries<\/code>. Differences generate a variance report<\/em> for ops, plus recon.adjustment<\/code> entries if needed.<\/p>\n\n\n\nWorkflow<\/h3>\n\n\n
\n
payment_id<\/code> \/ PSP reference \/ amount \/ currency<\/li>\nmatched<\/code>, missing_in_psp<\/code>, or missing_in_ledger<\/code><\/li>\n9) Fraud Signals & Observability (Brief)<\/h2>\n\n\n\n
RED Metrics & Tracing<\/h3>\n\n\n
\n
trace_id<\/code> across API \u2192 Kafka \u2192 workers \u2192 ledger<\/li>\n<\/ul>\n\n\n\n10) Reliability Targets & Error Budgets<\/h2>\n\n\n\n
\n
Outbox, DLQ, and Replay<\/h3>\n\n\n
11) Throughput & Cost Modeling<\/h2>\n\n\n\n
\n
transactions<\/code> by month, index by (merchant_id<\/code>, created_at<\/code>), use logical replication for analytics.<\/li>\n<\/ul>\n\n\n\n12) Multi-Region & Disaster Recovery<\/h2>\n\n\n\n
\n
13) Putting It All Together (What to Say in a Staff Interview)<\/h2>\n\n\n
\n
trace_id<\/code> linking API, Kafka, ledger, and reconciliation.\u201d<\/li>\n<\/ul>\n\n\n
\n\n\n