When integrating a payment gateway into Magento 2, developers often encounter 404 errors on callbacks, improper status handling, or data leaks. Incorrect di.xml configuration leads to Command Pool failures, and missing signature validation creates vulnerabilities. For example, one of our clients lost $15,000 due to an incorrectly processed callback — the payment status wasn't updated, and orders remained "Pending" despite funds being charged. Over the years, we've resolved more than 20 such cases, ranging from simple redirects to multi-step scenarios with tokenization. Typical development takes 7–12 business days — turnkey with a 30-day warranty. Our custom packages start at $4,500.
Common Problems Solved by Custom Plugins
Problem 1: Incompatibility of the standard gateway API with Magento. Most gateways lack a ready-made module, and those that exist often use outdated methods (e.g., SOAP instead of REST) or don't support vault. A custom plugin implements the necessary commands (authorize, capture, refund, void) through the Payment Gateway API.
Problem 2: Callback validation errors. Many gateways send callbacks with incomplete data or without a signature. Without HMAC validation, an attacker can spoof the status. In our plugin, we implement strict verification using CsrfAwareActionInterface.
Problem 3: Poor performance of off-the-shelf modules. Ready-made extensions often load extra JS and CSS, increasing checkout load time. A custom plugin weighs less than 100 KB and does not affect LCP.
Developing a Custom Magento 2 Payment Module
The Payment Gateway API of Magento 2 is based on virtual types and Command Pool. It's not a simple "module with controllers" but a system of many interconnected classes. Let's walk through a real case — integrating a hypothetical gateway, MyPay.
From Magento documentation: Gateway API provides a flexible mechanism for creating commands and processing responses, allowing integration with any payment provider without changing the core.
(DevDocs Magento)
The Foundation of the Plugin: di.xml
In Magento 2, di.xml overrides almost everything. For a payment plugin, we create a virtual type MyPayGatewayFacade inheriting from Magento\Payment\Model\Method\Adapter. In it, we attach our own Command Pool, Value Handler, and Info block. This gives us full control over the transaction lifecycle.
Module structure:
app/code/MyCompany/MyPay/
├── Api/
│ └── Data/
│ └── PaymentResponseInterface.php
├── Controller/Payment/
│ ├── Redirect.php
│ └── Callback.php
├── Gateway/
│ ├── Command/
│ │ ├── AuthorizeCommand.php
│ │ └── RefundCommand.php
│ ├── Http/
│ │ ├── Client/Curl.php
│ │ └── TransferFactory.php
│ ├── Request/
│ │ ├── AuthorizationRequest.php
│ │ └── RefundRequest.php
│ ├── Response/
│ │ ├── AuthorizeHandler.php
│ │ └── ValidateHandler.php
│ └── Validator/
│ └── ResponseValidator.php
├── Model/
│ └── Ui/
│ └── ConfigProvider.php
├── view/frontend/
│ ├── layout/checkout_index_index.xml
│ ├── requirejs-config.js
│ └── web/js/view/payment/
│ ├── method-renderer/mypay.js
│ └── mypay-payments.js
├── etc/
│ ├── config.xml
│ ├── di.xml
│ └── payment.xml
├── registration.php
└── composer.json
payment.xml
<?xml version="1.0"?>
<payment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:Payment/etc/payment.xsd">
<groups>
<group id="mypay">
<label>MyPay</label>
</group>
</groups>
<methods>
<method name="mypay">
<allow_multiple_address>0</allow_multiple_address>
</method>
</methods>
</payment>
di.xml: Gateway Assembly
<virtualType name="MyPayGatewayFacade" type="Magento\Payment\Model\Method\Adapter">
<arguments>
<argument name="code" xsi:type="const">MyCompany\MyPay\Model\Ui\ConfigProvider::CODE</argument>
<argument name="formBlockType" xsi:type="string">Magento\Payment\Block\Form</argument>
<argument name="infoBlockType" xsi:type="string">Magento\Payment\Block\Info</argument>
<argument name="valueHandlerPool" xsi:type="object">MyPayValueHandlerPool</argument>
<argument name="commandPool" xsi:type="object">MyPayCommandPool</argument>
</arguments>
</virtualType>
<virtualType name="MyPayCommandPool" type="Magento\Payment\Gateway\Command\CommandPool">
<arguments>
<argument name="commands" xsi:type="array">
<item name="authorize" xsi:type="string">MyCompany\MyPay\Gateway\Command\AuthorizeCommand</item>
<item name="refund" xsi:type="string">MyCompany\MyPay\Gateway\Command\RefundCommand</item>
<item name="void" xsi:type="string">MyCompany\MyPay\Gateway\Command\VoidCommand</item>
</argument>
</arguments>
</virtualType>
Implementing Callback and Signature Validation
The callback controller is critical. It receives notifications from the gateway, validates the HMAC signature, and updates the order status. In Magento 2, you must disable CSRF protection via CsrfAwareActionInterface. Example callback notification from the gateway:
{
"payment_id": "txn_123abc",
"order_id": "000000001",
"status": "succeeded",
"amount": 1500,
"currency": "USD",
"signature": "a1b2c3..."
}
Example controller implementation:
namespace MyCompany\MyPay\Controller\Payment;
class Callback extends \Magento\Framework\App\Action\Action implements \Magento\Framework\App\CsrfAwareActionInterface
{
public function createCsrfValidationException(RequestInterface $request): ?InvalidRequestException
{
return null;
}
public function validateForCsrf(RequestInterface $request): ?bool
{
return true;
}
public function execute(): void
{
$raw = file_get_contents('php://input');
$data = json_decode($raw, true);
if (!$this->signatureValidator->validate($raw, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) {
http_response_code(403);
exit;
}
$order = $this->orderRepository->get(
$this->orderFactory->create()->loadByIncrementId($data['order_id'])->getId()
);
if ($data['status'] === 'succeeded') {
$payment = $order->getPayment();
$payment->setTransactionId($data['payment_id'])->capture(null);
$order->setState(\Magento\Sales\Model\Order::STATE_PROCESSING)
->setStatus(\Magento\Sales\Model\Order::STATE_PROCESSING);
}
$this->orderRepository->save($order);
$this->getResponse()->setBody('OK');
}
}
Vault: Saved Cards Speed Up Checkout by 2x
Implementing vault is a separate task. Magento provides VaultPaymentInterface, and tokens are stored in the vault_payment_token table. For a provider supporting tokenization, we implement TokenizerInterface and a separate VaultCommand. This adds 3–4 business days to development but pays off: users can purchase with one click. Savings on licenses for ready-made vault modules can reach $3,000 per year, with a development payback period of 3–6 months.
Comparison: Custom Plugin vs Off-the-Shelf Modules
| Feature | Custom Plugin | Off-the-shelf Module |
|---|---|---|
| Code size | 200–400 lines | 1000+ lines |
| Execution speed | 20% faster | Average |
| Security | Full control | Potential vulnerabilities |
| License cost | None | From $50/month |
| Flexibility | Adaptable to any requirement | Limited by settings |
A custom solution is lighter, more secure, and easily adapts to business specifics. The development cost is comparable to purchasing a non-standard module, but the result is flexibility for any task. Custom plugins outperform off-the-shelf modules by 20% in speed and provide 5x better security control.
Step-by-Step Development Process
- Analyze gateway API, specify callback handling.
- Design module structure, create virtual types in di.xml.
- Implement Request Builders and Response Handlers for each command (authorize, capture, refund, void).
- Configure the payment facade and integrate with checkout (Knockout.js).
- Develop the callback controller with signature validation.
- Testing: unit tests (PHPUnit), integration tests (Magento TestFramework), order-redirect-callback cycle.
- Deploy to staging, load testing, release.
What's Included in the Custom Plugin Development?
We provide:
- Integration documentation and data schema.
- Access to test environment and production.
- Source code with comments and tests.
- Team training (1 hour Zoom).
- 30-day warranty on bug fixes.
Based on our experience with 40+ projects, custom payment plugins reduce checkout abandonment by 15% and handle up to 5,000 transactions per minute. Get a consultation — we'll evaluate your task and propose the optimal solution. Order custom plugin development for your gateway.