Разработка кастомного плагина оплаты OpenCart

Разработка кастомного плагина оплаты OpenCart

OpenCart 3.x и 4.x имеют разную архитектуру расширений. В 3.x — классическая MVC-структура в папке catalog/. В 4.x — Event system + namespaced классы, структура стала ближе к современным фреймворкам. Кастомный плагин пишется под конкретную версию.

Разработка занимает 3–5 рабочих дней. Если нужна поддержка обеих версий — умножить на 1.5.

Структура плагина OpenCart 4.x

extension/mypay/
├── admin/
│   ├── controller/payment/mypay.php
│   ├── language/en-gb/payment/mypay.php
│   ├── language/ru-ru/payment/mypay.php
│   └── view/template/payment/mypay.twig
├── catalog/
│   ├── controller/payment/mypay.php
│   ├── language/ru-ru/payment/mypay.php
│   └── view/template/payment/mypay.twig
└── install.json

Каталог: контроллер оплаты

namespace Opencart\Catalog\Controller\Extension\Mypay\Payment;

class Mypay extends \Opencart\System\Engine\Controller
{
    public function index(): string
    {
        $this->load->language('extension/mypay/payment/mypay');

        $data['action'] = $this->url->link(
            'extension/mypay/payment/mypay.confirm',
            'language=' . $this->config->get('config_language')
        );
        $data['amount']   = $this->currency->format($this->session->data['mypay_total'], 'RUB', 1, false);
        $data['order_id'] = $this->session->data['order_id'];

        return $this->load->view('extension/mypay/payment/mypay', $data);
    }

    public function confirm(): void
    {
        $this->load->model('checkout/order');
        $orderId  = (int) $this->session->data['order_id'];
        $order    = $this->model_checkout_order->getOrder($orderId);
        $total    = (int) round($order['total'] * 100);

        $client   = new \Mypay\ApiClient(
            $this->config->get('payment_mypay_api_key'),
            $this->config->get('payment_mypay_secret_key')
        );

        $payment = $client->createPayment([
            'amount'       => $total,
            'currency'     => 'RUB',
            'order_id'     => $orderId,
            'callback_url' => HTTPS_CATALOG . 'index.php?route=extension/mypay/payment/mypay.callback',
            'success_url'  => HTTPS_CATALOG . 'index.php?route=checkout/success',
            'fail_url'     => HTTPS_CATALOG . 'index.php?route=checkout/failure',
        ]);

        if (!$payment['payment_url']) {
            $this->session->data['error'] = 'Ошибка создания платежа';
            $this->response->redirect(HTTPS_CATALOG . 'index.php?route=checkout/checkout');
            return;
        }

        // Сохранить payment_id в комментарий к заказу
        $this->model_checkout_order->addHistory(
            $orderId,
            $this->config->get('payment_mypay_pending_status'),
            'MyPay Payment ID: ' . $payment['payment_id'],
            false
        );

        $this->response->redirect($payment['payment_url']);
    }

    public function callback(): void
    {
        $raw    = file_get_contents('php://input');
        $data   = json_decode($raw, true);
        $secret = $this->config->get('payment_mypay_secret_key');

        $expectedSig = hash_hmac('sha256', $raw, $secret);
        if (!hash_equals($expectedSig, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) {
            http_response_code(403);
            exit('Forbidden');
        }

        $this->load->model('checkout/order');
        $orderId = (int) $data['order_id'];

        $statusMap = [
            'succeeded' => (int) $this->config->get('payment_mypay_complete_status'),
            'failed'    => (int) $this->config->get('payment_mypay_failed_status'),
            'cancelled' => (int) $this->config->get('payment_mypay_cancelled_status'),
        ];

        $newStatus = $statusMap[$data['status']] ?? null;
        if ($newStatus) {
            $this->model_checkout_order->addHistory(
                $orderId, $newStatus, 'MyPay: ' . $data['status'], $data['status'] === 'succeeded'
            );
        }

        http_response_code(200);
        echo 'OK';
        exit;
    }
}

Admin: настройки плагина

namespace Opencart\Admin\Controller\Extension\Mypay\Payment;

class Mypay extends \Opencart\System\Engine\Controller
{
    public function save(): void
    {
        $this->load->language('extension/mypay/payment/mypay');

        if (!$this->user->hasPermission('modify', 'extension/mypay/payment/mypay')) {
            $this->response->setOutput(json_encode(['error' => ['warning' => 'Нет прав']]));
            return;
        }

        $keys = ['status', 'api_key', 'secret_key', 'testmode', 'pending_status', 'complete_status', 'failed_status'];
        foreach ($keys as $key) {
            $this->config->set('payment_mypay_' . $key, $this->request->post['payment_mypay_' . $key] ?? '');
            $this->model_setting_setting->editSettingValue('payment_mypay', 'payment_mypay_' . $key, $this->request->post['payment_mypay_' . $key] ?? '');
        }

        $this->response->setOutput(json_encode(['success' => 'Настройки сохранены']));
    }
}

install.json

{
    "name": "MyPay Payment Gateway",
    "version": "1.0.0",
    "author": "Your Company",
    "link": "https://yourcompany.com",
    "type": "payment",
    "category": "payment"
}

Особенности OpenCart 3.x

В OpenCart 3.x структура папок другая: upload/catalog/controller/payment/mypay.php. Namespace не используется, классы называются ControllerPaymentMypay. Установка через Extension Installer (zip-архив) или вручную. Вместо install.json — файл upload/ layout.

Тестирование и отладка

OpenCart записывает ошибки в /system/storage/logs/. При разработке callback-а — использовать ngrok для доступа к localhost. Статусы заказов конфигурируются в admin → System → Order Statuses, их ID подставляются в настройки плагина.