Payment System

Purpose and Scope

This document details the payment processing system within Maho, covering payment method configuration, the fully integrated PayPal Express Checkout flow, payment data encryption, and payment observers. It also highlights the paypal:webhook:simulate CLI command for testing PayPal webhook events locally.

For broader context, see Quote System for quote to order conversion, and Order Processing for order lifecycle management.

---

Payment System Architecture

The Maho payment system offers a modular and extensible framework to support various payment methods, providing seamless integration layers for authorization, capture, refund, and void operations with a focus on PayPal Express Checkout.

Most payment methods extend from a base abstract class enabling consistent API usage across implementations.

Key Code Entities and Relationships

Sources:

• app/code/core/Maho/Paypal/Model/Method/Abstract.php:13-13
• app/code/core/Maho/Paypal/Model/Method/Vault.php:13-40
• app/code/core/Mage/Payment/Model/Info.php:77-95

---

PayPal Integration Flow

The PayPal module integrates tightly with the PayPal Server SDK (PaypalServerSdkLib) to provide a smooth Express Checkout experience supporting Standard, Advanced (inline card fields), and Vault payment methods.

Checkout and Webhook Interaction Sequence

Core Components

• API Client (Maho_Paypal_Model_Api_Client)
  Wraps PaypalServerSdkClient from the official PayPal Server SDK, managing OAuth authentication and exposing methods to create, capture, authorize, and refund PayPal orders. Supports explicit credential overrides per store and debug logging to var/log/paypal.log app/code/core/Maho/Paypal/Model/Api/Client.php21-103

• Checkout Controller (Maho_Paypal_CheckoutController)
  Handles AJAX endpoints for generating client tokens for frontend use and creating PayPal orders based on the current quote. It validates form keys, manages vault token usage, and stores PayPal order IDs on quote payments to track transactions during checkout app/code/core/Maho/Paypal/controllers/CheckoutController.php38-163

• Webhook Processor (Maho_Paypal_Model_Webhook_Processor)
  Processes webhook payloads from PayPal, mapping event types to specific handler models via the HANDLER_MAP. It deduplicates events by unique PayPal event IDs and updates their status after processing. Supports an unsafe processing mode for CLI-based webhook simulation app/code/core/Maho/Paypal/Model/Webhook/Processor.php13-70

• Webhook Handlers
  Dedicated classes handle specific webhook events.

  • OrderCompleted ensures fallback placement of the Maho order if frontend processing failed.
  • CaptureCompleted logs capture completion, registers captured transactions, and triggers invoice creation.
  • Other handlers manage authorization, disputes, and vault token lifecycle events.
    app/code/core/Maho/Paypal/Model/Webhook/Handler/OrderCompleted.php20-76 app/code/core/Maho/Paypal/Model/Webhook/Handler/CaptureCompleted.php13-54

• Helper (Maho_Paypal_Helper_Data)
  Provides methods to import PayPal payer addresses into the quote and place Maho orders from PayPal API results. It also saves vault tokens securely and handles sessionless checkout state fixes app/code/core/Maho/Paypal/Helper/Data.php17-152

Webhook Simulation Command

Maho includes the paypal:webhook:simulate CLI command which invokes Maho_Paypal_Model_Webhook_Processor::processUnsafe to allow developers to test webhook handling locally by supplying JSON payloads. This bypasses webhook signature verification to facilitate debugging and development.

---

Payment Data Encryption

Maho employs robust encryption mechanisms to secure sensitive payment details and tokens.

Encryption in Payment Info Model

Mage_Payment_Model_Info transparently encrypts and decrypts sensitive data fields when saved or retrieved:

• On getData('cc_number') or getData('cc_cid'), encrypted versions (cc_number_enc, cc_cid_enc) are decrypted on-demand.
• Encryption and decryption utilize Mage_Core_Helper_Data methods, which implement Sodium crypto or fallback methods.
• Additional payment information is stored in the 'additional_information' array, also secured.

app/code/core/Mage/Payment/Model/Info.php57-123

Vault Token Encryption

PayPal Vault tokens are stored in the database encrypted. The module listens to encryption key rotation events to re-encrypt tokens securely. See the vault method handling for encryption details [app/code/core/Maho/Paypal/Model/Method/Vault.php].

Encryption Key Regeneration Flow

Key rotation and data re-encryption are handled safely in a transaction via a CLI command. The process involves:

• Validating all encrypted data.
• Re-encrypting sensitive data in the admin user table.
• Re-encrypting core configuration data.
• Dispatching the 'encryption_key_regenerated' event for modules like PayPal to update their stored encrypted values.

Sources:

• app/code/core/Mage/Payment/Model/Info.php:57-123

---

Payment Observers

Maho extensively uses event observers for payment system integrity, maintenance cron jobs, and reacting to product catalog changes.

Key Observers in the Sales Module

Observer Method	Event	Purpose
cleanExpiredQuotes	Cron job: sales_clean_quotes	Cleans out expired/deactivated quotes periodically
catalogProductSaveAfter	catalog_product_save_after	Marks quotes for recollect if product disabled
catalogProductStatusUpdate	catalog_product_status_update	Handles mass product status change for quote updates
substractQtyFromQuotes	catalog_product_delete_before	Adjusts quote quantities when product deleted

Admin Activity Logging

Using the Maho_AdminActivityLog module, changes to sensitive payment configurations are recorded and encrypted to maintain an audit trail.

Sources:

• app/code/core/Mage/Sales/Model/Observer.php:28-205

---

Payment Method Configuration

Payment methods are declared via XML configuration (config.xml) and made administratively configurable through the system configuration UI (system.xml).

PayPal Vault Method

• The Maho_Paypal_Model_Method_Vault provides saved payment methods for logged-in customers.
• It checks for active vault tokens linked to the customer before enabling the payment method in checkout.
• Supports admin-side order creation utilizing saved vault tokens and integrates with the PayPal API for order creation, authorization, and capture.
• Assigns vault token ID and label to the payment info instance for processing app/code/core/Maho/Paypal/Model/Method/Vault.php22-40

PayPal Order ID Tracking

• PayPal order IDs are stored on both the quote payment and order payment tables for reconciliation and webhook correlation.
• The quote at checkout stores the PayPal order ID as paypal_order_id in additional information, allowing mapping in webhook processing and order placement.

OnePage Checkout Integration

• The Mage_Checkout_Model_Type_Onepage class coordinates checkout progression, method selection, billing, and order saving.
• It manages quote lifecycle and session states required for payments including setting checkout method after webhook order placement for seamless user experience app/code/core/Mage/Checkout/Model/Type/Onepage.php13-211

---

Summary

Maho's payment system is a robust, secure, and extensible architecture enabling multiple payment methods with a focus on a modernized, tokenized PayPal Express Checkout experience. The system integrates frontend APIs, backend webhook handlers, encrypted storage of sensitive data, and event observers to ensure integrity and maintainability.

The inclusion of CLI tools to simulate webhook events and rotate encryption keys ensures robust development and security workflows.

---

Sources:

• app/code/core/Maho/Paypal/controllers/CheckoutController.php:38-163
• app/code/core/Maho/Paypal/Model/Api/Client.php:21-103
• app/code/core/Maho/Paypal/Model/Webhook/Processor.php:13-78
• app/code/core/Maho/Paypal/Model/Webhook/Handler/OrderCompleted.php:20-76
• app/code/core/Maho/Paypal/Model/Webhook/Handler/CaptureCompleted.php:13-54
• app/code/core/Maho/Paypal/Helper/Data.php:17-152
• app/code/core/Mage/Payment/Model/Info.php:57-123
• app/code/core/Maho/Paypal/Model/Method/Vault.php:22-40
• app/code/core/Mage/Checkout/Model/Type/Onepage.php:13-211
• app/code/core/Mage/Sales/Model/Observer.php:28-205