Кастомний платіжний плагін Magento 2 — розробка та інтеграція

При інтеграції платіжного шлюзу в 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 готові модулі

Кастомне рішення легше, безпечніше та легко адаптується під специфіку бізнесу. Вартість розробки порівнянна з покупкою нестандартного модуля, а результат — гнучкість під будь-які завдання.

Покроковий процес розробки

1. Аналіз API шлюзу, специфікація callback-ів.
2. Проєктування структури модуля, створення віртуальних типів у di.xml.
3. Реалізація Request Builders та Response Handlers для кожної команди (authorize, capture, refund, void).
4. Налаштування платіжного фасаду та інтеграція з checkout (Knockout.js).
5. Розробка callback-контролера з валідацією підпису.
6. Тестування: юніт-тести (PHPUnit), інтеграційні тести (Magento TestFramework), цикл замовлення-редирект-callback.
7. Деплой на staging, навантажувальне тестування, реліз.

Що входить у роботу над кастомним плагіном?

Ми надаємо:

• Документацію з інтеграції та схеми даних.
• Доступи до тестового контуру та production.
• Вихідний код з коментарями та тестами.
• Навчання команди (1 година zoom).
• Гарантію 30 днів на виправлення помилок.

Отримайте консультацію — ми оцінимо завдання та запропонуємо оптимальне рішення. Замовте розробку кастомного плагіна під ваш шлюз.