01. Architecture Overview & Checkout Idempotency
This document provides the high-level system architecture and a deep dive into the resilient Commerce/Checkout engine, specifically focusing on our Idempotency Guarantees.1. High-Level System Architecture#
The Itinera platform operates on a decoupled architecture, ensuring strict boundaries between the user interface, business logic, and third-party integrations.2. The Commerce Engine: Order Creation & Idempotency#
When dealing with financial transactions, network failures, double-clicks, or impatient users can lead to duplicate orders. We solve this using strict Idempotency Keys and deterministic intent reuse.The Problem#
A user clicks "Checkout" but their internet drops. They click it again. We must prevent charging them twice or creating two identical orders.The Solution: idempotency_key#
Every checkout request from the client includes a unique idempotency_key (nullable, max 64 chars).1.
Request Validation: InitiateCheckoutRequest validates the key format.
2.
Intent Reuse: CheckoutService::findReusableCheckout($userId, $idempotencyKey) scans the DB for an existing, unpaid order matching that key.
3.
Short-circuiting: If a match is found, we skip talking to Paymob and simply return the existing client_secret and checkout_url.
4.
Creation: If no match exists, OrderRepository safely provisions a new order and we persist the idempotency_key.
3. Webhook Fulfillment & Re-entrancy Guards#
Idempotency extends beyond order creation to the fulfillment phase. Paymob may send the same successful webhook multiple times due to network retries.HMAC Validation (SEC-05)#
Before processing any webhook, PaymobGateway::verifyWebhook strictly checks the HMAC SHA-512 signature. In production, if the PAYMOB_HMAC secret is missing, it fails-fast throwing an Exception, preventing attackers from sending empty-secret forged webhooks.The Fulfillment Guard#
When a valid webhook triggers the FulfillOrderListener, we implement a re-entrancy guard to prevent provisioning the user's subscription twice:This ensures absolute consistency from the moment the user taps "Pay" to the moment their account is upgraded. Modified at 2026-08-25 22:41:45
