How fbrusatti/active_merchant works
Primary Components
• Core Library – At the heart of the project is the “active_merchant” namespace, which aggregates the key utility modules (connection, error handling, parameter validation, and helper code). This serves as the backbone supporting all payment operations.
• Billing Module – This submodule contains the core billing logic such as credit card handling (credit card, formatting, and validation), response parsing, and request preparation.
• Integration Layer – Found in “lib/active_merchant/billing/integrations” this layer handles offsite payment integration, managing callbacks, notifications, and the redirection flows required by some providers.
• Generators – The “generators” directories (gateway and integration) indicate templating capabilities to scaffold new gateway integrations or extend existing functionality, suggesting an emphasis on extensibility.
• Test Infrastructure – Both “test/unit” and “test/remote” directories indicate a rigorous approach to unit testing and integration testing (including real remote gateway calls for validation).
Out Their Relationships and Data Flow
• Application Interface:
• The library is designed to integrate into a Rails or Ruby application via its init.rb and plugin mechanism.
• The client code obtains a gateway object (e.g., TrustCommerceGateway) and passes in a CreditCard instance and payment amount.
• Credit Card Processing:
• The Credit Card object (and related modules like expiry_date and verification via CVV classes) plays a central role in validating data before any payment is attempted.
• Gateway Adapter Communication:
• Once validated, the system uses the chosen gateway adapter from the “gateways” directory. Each adapter implements a common interface (derived from a shared Base class) to communicate with external payment APIs.
• Integration and Notification:
• For offsite payments, the integration modules handle helper routines for creating forms, handling notifications, and managing return/callback data flows.
• Utility / Support Functions:
• Supporting components such as logging, error handling, country codes, and other small utility classes reside in various “lib” subdirectories (e.g., lib/connection, lib/utils) and support the billing and gateway operations.
Architectural Patterns and Design Principles
• Modular Design / Plugin Architecture:
• The design promotes ease of extension. New gateways and integration points are added by implementing standardized templates—noted by the presence of generator scripts and templates.
• Abstraction via Common Interfaces:
• A shared abstract Gateway class and consistent request/response pattern across different adapters encapsulate varying external APIs behind a unified interface.
• Separation of Concerns:
• Distinct directories and modules isolate credit card processing, gateway communications, integration flows, and helper utilities.
• Test-Driven Development:
• A broad suite of both unit and remote tests ensures that payment flows and gateway interactions work reliably.