Magento's payment gateway architecture is one of its most powerful extensibility points. The Payment Provider Gateway (introduced in 2.1) makes it possible to integrate any payment provider without modifying core code. Here's how to build a production-ready custom payment integration.
Understanding the Architecture
Magento's payment system has three layers: the Payment Method (what the customer selects at checkout), the Payment Adapter (connects Magento's interface to your gateway's API), and Commands (discrete operations like Authorize, Capture, Refund, Void). Each command is an independent class, making the system highly testable and maintainable.
Essential Files for a Gateway Module
- etc/config.xml — default configuration values
- etc/payment.xml — payment method metadata (active, title, sort_order)
- Model/Adapter.php — implements AdapterInterface, wraps your payment SDK
- Gateway/Request/AuthorizeRequest.php — builds the authorization request payload
- Gateway/Response/AuthorizeHandler.php — processes the authorization response
- Gateway/Validator/ResponseValidator.php — validates response codes and signatures
- view/frontend/web/js/view/payment/method-renderer — checkout UI component
Handling 3DS Authentication
Modern payment processors require 3D Secure (3DS2) authentication. This introduces a redirect or iframe step that interrupts the checkout flow. Implement a custom action controller to handle the 3DS callback, update the payment status, and redirect the customer back to the order success page. Store 3DS authentication data in the payment additional_information array for audit purposes.
Testing and PCI Compliance
Payment integrations require extensive testing: happy path (successful payment), declined cards, network timeouts, duplicate order submissions, and refund flows. Use the gateway's sandbox environment and a test card matrix. Never log full card numbers or CVV — implement log sanitization that redacts sensitive fields. Consider PCI SAQ-A compliance requirements if using iframe-based card capture.
