Skip to content

New Checkout Flow - Overview

Why We're Redesigning

The current checkout flow has critical architectural issues identified in the Current Situation Analysis:

  1. Order-Payment Coupling - Failed payments create duplicate orders in the database
  2. Unclear State Management - No explicit tracking of order/payment lifecycle
  3. Poor Error Handling - Users can't retry payments or switch methods easily
  4. Legacy API Dependencies - Still using deprecated SOAP APIs from CM.com
  5. Monolithic Architecture - Single controller handling all checkout logic

These issues lead to:

  • Database pollution with incomplete orders
  • Support overhead from debugging failed transactions
  • Technical debt blocking future improvements

Core Design Principles

1. Decouple Orders from Payments

Current (problematic): 

Cart → Order → Payment (1:1:1 coupling)
Failed payment = new cart + new order

New (proposed): 

Cart → Order → Payment Attempt 1
             → Payment Attempt 2 (on failure)
             → Payment Attempt 3 (method switch)

Benefits:

  • One order can have multiple payment attempts
  • No duplicate orders in database
  • Clear payment history per order
  • Users can retry or switch payment methods

2. Explicit State Tracking

Each order and payment attempt has explicit status values:

Order States: created → pending → confirmed → shipped → delivered

Payment States: initiated → processing → success/failed/cancelled

3. Separation of Concerns

Replace monolithic OrderOpcController with dedicated controllers per step:

  • CheckoutAuthController - Authentication
  • CheckoutPaymentController - Payment method selection
  • PaymentProcessController - Payment execution
  • PaymentValidationController - Payment result handling

4. Modern API Integration

Migrate from deprecated SOAP APIs to CM.com REST API:

  • Better error handling
  • More reliable payment status tracking
  • Support for modern payment methods
  • Future-proof architecture

5. Comprehensive Error Handling

Structured unhappy paths with:

  • Retry logic for failed payments
  • Method switching for cancelled payments
  • Order re-evaluation when cart changes
  • Clear error messages and user guidance

Key Architectural Changes

Order Lifecycle

  1. Created State (new) - Order exists but not locked

    • User can still modify cart/address
    • Order updates automatically on return to payment selection

  2. Pending State - Order is locked, payment in progress

    • Cart/address modifications blocked
    • Can have multiple payment attempts

  3. Confirmed State - Payment successful, order finalized

Payment Attempt Tracking

New payment_attempts table tracks:

  • All payment attempts per order
  • Payment method used
  • CM.com transaction IDs
  • Error codes and messages
  • Retry counts
  • Timestamps for audit trail

Checkout Steps

Step URL Purpose
0 /cart Cart review
1 /checkout/auth Login/Register/Guest
2 /checkout/payment-selection Select method, create order
2a/2b /checkout/creditcard-selection Card-specific sub-steps
3 /checkout/payment Execute payment
4 /checkout/validate Validate result
5 /checkout/confirmation Order confirmed

Documentation Structure

The proposed design is split across multiple documents: