Phase 2: Commerce & Checkout Engine

This document details the strictly decoupled, synchronous flow of the Commerce Engine when a user initiates a checkout.

1. High-Level Concept

The checkout engine is built around a single CheckoutController that validates the HTTP request and delegates the business logic to a reusable CheckoutService. The system is designed to gracefully handle network partitions using Idempotency Keys.

2. API Contract & Validation

The flow begins when the client hits POST /api/checkout. The payload is intercepted and validated by InitiateCheckoutRequest:

3. The `idempotency_key` and Intent Reuse

When a user taps the "Checkout" button, the frontend generates a UUID and sends it as the idempotency_key.

Why is this necessary?

If the user's connection drops after tapping "Pay", but the request reached our server, we will have created a Payment Intent at Paymob. If the user retries, we DO NOT want to generate a second Payment Intent or a duplicate Order in the database.

The Resolution Logic

Inside CheckoutService.php, before querying the Payment Gateway, the system checks for a reusable intent:

If no reusable intent is found, we open a DB::transaction() to ensure atomic creation of the Order and the Paymob intent.

4. Sequence Diagram: Checkout Initialization

This Mermaid diagram illustrates the lifecycle of a single /api/checkout request, showcasing the idempotency split.

5. Architectural Principles Applied

Fat Services, Thin Controllers: The CheckoutController is purely responsible for HTTP wrapping. All transactional logic lives in CheckoutService.

Fail-Fast Intent Generation: We query Paymob before committing the order to the database. If Paymob is down, we return a 503 and do not leave an orphaned, unpaid Order row in our database.

Idempotent by Default: The combination of user_id and idempotency_key ensures that users cannot accidentally double-charge themselves on erratic network connections.

Phase 2: Commerce &amp; Checkout Engine

1. High-Level Concept#

2. API Contract & Validation#

3. The idempotency_key and Intent Reuse#

Why is this necessary?#

The Resolution Logic#

4. Sequence Diagram: Checkout Initialization#

5. Architectural Principles Applied#