При интеграции платёжного шлюза в Magento 2 разработчики часто сталкиваются с ошибками 404 на callback, неправильной обработкой статусов или утечкой данных. Неверная конфигурация di.xml приводит к сбоям Command Pool, а отсутствие валидации подписи — к уязвимостям. Например, один из заказчиков потерял $15 000 из-за неверно обработанного callback: статус оплаты не обновлялся, и заказы уходили в "Pending", хотя деньги были списаны. За время работы мы решили более 20 таких кейсов, от простых редиректов до многошаговых сценариев с токенизацией. Типичная разработка занимает 7–12 рабочих дней — под ключ с гарантией 30 дней.
Какие проблемы решает кастомный плагин?
Проблема 1: Несовместимость стандартного API шлюза с Magento. Большинство шлюзов не имеют готового модуля, а те, что есть, часто работают через устаревшие методы (например, SOAP вместо REST) или не поддерживают vault. Кастомный плагин реализует нужные команды (authorize, capture, refund, void) через Payment Gateway API.
Проблема 2: Ошибки валидации callback. Многие шлюзы присылают callback с неполными данными или без подписи. Без HMAC-валидации злоумышленник может подменить статус. В нашем плагине мы реализуем строгую проверку с использованием CsrfAwareActionInterface.
Проблема 3: Низкая производительность готовых модулей. Готовые расширения часто загружают лишние JS и CSS, увеличивая время загрузки checkout. Кастомный плагин весит меньше 100 KB и не влияет на LCP.
Как разработать кастомный плагин оплаты Magento 2?
Payment Gateway API Magento 2 основан на виртуальных типах и Command Pool. Это не простой «модуль с контроллерами», а система из множества взаимосвязанных классов. Разберём на реальном кейсе — интеграция гипотетического шлюза MyPay.
Из документации Magento: "Gateway API предоставляет гибкий механизм для создания команд и обработки ответов, что позволяет интегрировать любой платёжный провайдер без изменения ядра." (Источник: DevDocs Magento)
Почему di.xml — основа плагина?
В Magento 2 di.xml переопределяет почти всё. Для плагина оплаты мы создаём виртуальный тип MyPayGatewayFacade, наследуемый от Magento\Payment\Model\Method\Adapter. В нём подключаем свой Command Pool, Value Handler и Info блок. Так получаем полный контроль над жизненным циклом транзакции.
Структура модуля:
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
<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> Как реализовать callback и валидацию подписи?
Callback-контроллер — критический элемент. Он получает уведомления от шлюза, проверяет подпись HMAC и обновляет статус заказа. В Magento 2 необходимо отключить CSRF-защиту через CsrfAwareActionInterface. Пример callback-уведомления от шлюза:
{ "payment_id": "txn_123abc", "order_id": "000000001", "status": "succeeded", "amount": 1500, "currency": "USD", "signature": "a1b2c3..." } Пример реализации контроллера:
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: сохранённые карты ускоряют checkout в 2 раза
Реализация vault — отдельная задача. Magento предоставляет VaultPaymentInterface, токены хранятся в vault_payment_token. Для провайдера, поддерживающего токенизацию, реализуется TokenizerInterface и отдельный VaultCommand. Это добавляет 3–4 рабочих дня к разработке, но окупается: пользователи совершают покупки в один клик. Экономия на лицензиях готовых модулей с vault может достигать $3000 в год, а окупаемость разработки составляет 3–6 месяцев.
Сравнение: кастомный плагин vs готовые модули
| Характеристика | Кастомный плагин | Готовый модуль |
|---|---|---|
| Размер кода | 200–400 строк | 1000+ строк |
| Скорость выполнения | на 20% быстрее | средняя |
| Безопасность | полный контроль | возможны уязвимости |
| Стоимость лицензии | отсутствует | от $50/мес |
| Гибкость | под любые требования | ограничен настройками |
Кастомное решение легче, безопаснее и легко адаптируется под специфику бизнеса. Стоимость разработки сопоставима с покупкой нестандартного модуля, а результат — гибкость под любые задачи.
Пошаговый процесс разработки
- Анализ API шлюза, спецификация callback-ов.
- Проектирование структуры модуля, создание виртуальных типов в di.xml.
- Реализация Request Builders и Response Handlers для каждой команды (authorize, capture, refund, void).
- Настройка платежного фасада и интеграция с checkout (Knockout.js).
- Разработка callback-контроллера с валидацией подписи.
- Тестирование: юнит-тесты (PHPUnit), интеграционные тесты (Magento TestFramework), цикл заказ-редирект-callback.
- Деплой на staging, нагрузочное тестирование, релиз.
Что входит в работу над кастомным плагином?
Мы предоставляем:
- Документацию по интеграции и схеме данных.
- Доступы к тестовому контуру и production.
- Исходный код с комментариями и тестами.
- Обучение команды (1 час zoom).
- Гарантию 30 дней на исправление ошибок.
Получите консультацию — мы оценим задачу и предложим оптимальное решение. Закажите разработку кастомного плагина под ваш шлюз.