Architecture - Magento_Checkout Module

Checkout Architecture Overview

The Magento Checkout module implements a two-step checkout process by default: shipping and payment/review. The architecture heavily relies on Knockout.js for frontend components, with a RESTful backend API that enables headless checkout implementations. The checkout session maintains state across the multi-step process using PHP sessions and browser-side storage.

Key Architectural Principle

The checkout separates guest and authenticated customer flows at the API level, with dedicated interfaces (Guest* vs regular) that handle authorization differently while sharing core business logic.

Service Contracts (26 Interfaces)

Management Interfaces

These interfaces define the checkout operations for customers and guests:

PaymentInformationManagementInterface

Save payment info and place order for authenticated customers

savePaymentInformationAndPlaceOrder($cartId, PaymentInterface, AddressInterface)
savePaymentInformation($cartId, PaymentInterface, AddressInterface)
getPaymentInformation($cartId)

GuestPaymentInformationManagementInterface

Same operations for guest customers using cart mask ID

savePaymentInformationAndPlaceOrder($cartId, $email, PaymentInterface, AddressInterface)
savePaymentInformation($cartId, $email, PaymentInterface, AddressInterface)

ShippingInformationManagementInterface

Handle shipping address and method selection

saveAddressInformation($cartId, ShippingInformationInterface)

TotalsInformationManagementInterface

Calculate and return cart totals based on address

calculate($cartId, TotalsInformationInterface)

Data Interfaces

Transfer objects for checkout data:

ShippingInformationInterface

getShippingAddress()
getBillingAddress()
getShippingMethodCode()
getShippingCarrierCode()

PaymentDetailsInterface

getPaymentMethods()
getTotals()

TotalsInformationInterface

getAddress()
getShippingMethodCode()
getShippingCarrierCode()

AgreementsValidatorInterface

isValid($agreementIds)

Security Interfaces

PaymentProcessingRateLimiterInterface

Rate limit payment processing attempts

Default: CaptchaPaymentProcessingRateLimiter

PaymentSavingRateLimiterInterface

Rate limit payment information save attempts

Default: CaptchaPaymentSavingRateLimiter

Session Management

Checkout Session

The Magento\Checkout\Model\Session class manages the checkout state with a dedicated session namespace.

<!-- di.xml Virtual Type Configuration -->
<virtualType name="Magento\Checkout\Model\Session\Storage"
             type="Magento\Framework\Session\Storage">
    <arguments>
        <argument name="namespace" xsi:type="string">checkout</argument>
    </arguments>
</virtualType>

<type name="Magento\Checkout\Model\Session">
    <arguments>
        <argument name="storage" xsi:type="object">
            Magento\Checkout\Model\Session\Storage
        </argument>
    </arguments>
</type>

Key Session Methods

getQuote()

Returns the current quote object, loading or creating as needed

getQuoteId()

Returns the quote ID from session storage

setQuoteId($quoteId)

Stores quote ID in session

clearQuote()

Clears quote from session (used after order placement)

getLastSuccessQuoteId()

Returns quote ID of last successful order

getLastRealOrderId()

Returns increment ID of last placed order

Session Quote Synchronization

The SalesQuoteSaveAfterObserver listens to sales_quote_save_after event to keep the session's quote ID synchronized when quotes are saved.

Frontend Architecture (Knockout.js)

Component Structure

The checkout frontend uses 208 JavaScript components organized in a hierarchical structure. Components are loaded via RequireJS and managed by Knockout.js observables.

Core Components

checkout - Main checkout container
steps - Multi-step navigation
shipping - Shipping step container
payment - Payment step container
sidebar - Order summary sidebar

Data Models

quote - Quote state management
checkout-data - Checkout data persistence
customer-data - Customer section data
shipping-rates - Available shipping methods
payment-methods - Available payment methods

CustomerData Sections (14 Classes)

CustomerData provides cached, invalidatable frontend data sections:

Cart

Mini-cart contents

DirectoryData

Countries and regions

DefaultItem

Default item renderer

REST API Architecture (12 Endpoints)

The checkout module exposes REST endpoints for both guest and authenticated checkout flows. Guest endpoints use a masked cart ID for security.

Method	Endpoint	Auth	Operation
POST	/V1/carts/mine/shipping-information	Customer	Save shipping address and method
POST	/V1/guest-carts/:cartId/shipping-information	Guest	Save shipping (guest)
POST	/V1/carts/mine/payment-information	Customer	Save payment and place order
POST	/V1/guest-carts/:cartId/payment-information	Guest	Save payment and place order (guest)
GET	/V1/carts/mine/payment-information	Customer	Get payment methods and totals
GET	/V1/guest-carts/:cartId/payment-information	Guest	Get payment info (guest)
POST	/V1/carts/mine/set-payment-information	Customer	Save payment without order
POST	/V1/guest-carts/:cartId/set-payment-information	Guest	Save payment without order (guest)
POST	/V1/carts/mine/totals-information	Customer	Calculate totals for address
POST	/V1/guest-carts/:cartId/totals-information	Guest	Calculate totals (guest)
POST	/V1/carts/:cartId/shipping-information	Admin	Save shipping (admin)
POST	/V1/carts/:cartId/totals-information	Admin	Calculate totals (admin)

Directory Structure

module-checkout/
├── Api/                          # 26 service contract interfaces
│   ├── Data/                     # Data transfer interfaces
│   │   ├── PaymentDetailsInterface.php
│   │   ├── ShippingInformationInterface.php
│   │   └── TotalsInformationInterface.php
│   ├── GuestPaymentInformationManagementInterface.php
│   ├── GuestShippingInformationManagementInterface.php
│   ├── PaymentInformationManagementInterface.php
│   ├── PaymentProcessingRateLimiterInterface.php
│   └── ShippingInformationManagementInterface.php
├── Block/                        # 72 block classes
│   ├── Checkout/                 # Checkout page blocks
│   ├── Cart/                     # Cart blocks
│   ├── Onepage/                  # One-page checkout blocks
│   └── Link.php                  # Checkout link block
├── Controller/                   # 50 controllers
│   ├── Cart/                     # Cart actions
│   ├── Onepage/                  # Checkout step actions
│   ├── Sidebar/                  # Sidebar AJAX actions
│   └── Index/                    # Main checkout page
├── CustomerData/                 # 14 customer data sections
│   ├── Cart.php
│   ├── DefaultItem.php
│   └── DirectoryData.php
├── Helper/                       # 6 helper classes
│   ├── Data.php                  # General checkout helpers
│   └── ExpressRedirect.php       # Express checkout redirect
├── Model/                        # 80 model classes
│   ├── Session.php               # Checkout session
│   ├── Cart.php                  # Cart model
│   ├── PaymentInformationManagement.php
│   ├── GuestPaymentInformationManagement.php
│   ├── ShippingInformationManagement.php
│   └── Type/                     # Checkout type models
├── Observer/                     # 6 observer classes
│   └── SalesQuoteSaveAfterObserver.php
├── Plugin/                       # 2 plugin classes
│   └── RecollectQuoteOnCustomerGroupChange.php
├── ViewModel/                    # 2 view models
├── view/
│   └── frontend/
│       ├── layout/               # 32 layout XML files
│       ├── templates/            # Checkout templates
│       └── web/
│           └── js/               # 208 JavaScript components
└── etc/
    ├── di.xml                    # 14 preferences, 1 plugin
    ├── events.xml                # 1 observer
    ├── webapi.xml                # 12 REST endpoints
    └── frontend/                 # Frontend-specific config