Інтеграція платіжного шлюзу в WooCommerce

Інтеграція платіжного шлюзу в WooCommerce

WooCommerce надає стандартизований інтерфейс для платіжних шлюзів через клас WC_Payment_Gateway. Готові плагіни існують для більшості популярних провайдерів, але часто вони застарілі, містять баги або не підтримують потрібний функціонал — повернення через API, часткових capture, webhook-и. У таких випадках пишеться власний gateway-клас.

Розробка кастомного gateway займає 2–4 робочих дня включаючи тести.

Структура плагіну

wp-content/plugins/mypay-gateway/
├── mypay-gateway.php          # Точка входу, реєстрація
├── includes/
│   ├── class-wc-gateway-mypay.php
│   └── class-mypay-api-client.php
└── assets/
    └── js/checkout.js

Базовий клас gateway

class WC_Gateway_MyPay extends WC_Payment_Gateway
{
    public function __construct()
    {
        $this->id                 = 'mypay';
        $this->method_title       = 'MyPay';
        $this->has_fields         = false;
        $this->supports           = ['products', 'refunds'];

        $this->init_form_fields();
        $this->init_settings();

        $this->title       = $this->get_option('title');
        $this->description = $this->get_option('description');
        $this->api_key     = $this->get_option('api_key');
        $this->secret_key  = $this->get_option('secret_key');
        $this->testmode    = 'yes' === $this->get_option('testmode');

        add_action('woocommerce_update_options_payment_gateways_' . $this->id,
            [$this, 'process_admin_options']);
        add_action('woocommerce_api_mypay_callback', [$this, 'handle_webhook']);
    }

    public function init_form_fields(): void
    {
        $this->form_fields = [
            'enabled'    => ['title' => 'Включити', 'type' => 'checkbox', 'default' => 'yes'],
            'title'      => ['title' => 'Назва', 'type' => 'text', 'default' => 'Банківська карта'],
            'api_key'    => ['title' => 'API Key', 'type' => 'password'],
            'secret_key' => ['title' => 'Secret Key', 'type' => 'password'],
            'testmode'   => ['title' => 'Тестовий режим', 'type' => 'checkbox', 'default' => 'no'],
        ];
    }
}

Процес оплати

public function process_payment(int $order_id): array
{
    $order  = wc_get_order($order_id);
    $client = new MyPay_API_Client($this->api_key, $this->secret_key, $this->testmode);

    $response = $client->createPayment([
        'amount'      => (int) ($order->get_total() * 100),
        'currency'    => get_woocommerce_currency(),
        'order_id'    => $order_id,
        'description' => 'Замовлення #' . $order->get_order_number(),
        'success_url' => $this->get_return_url($order),
        'fail_url'    => wc_get_checkout_url(),
        'callback_url'=> home_url('/wc-api/mypay_callback'),
        'customer'    => [
            'email' => $order->get_billing_email(),
            'phone' => $order->get_billing_phone(),
        ],
    ]);

    if ($response['status'] === 'error') {
        wc_add_notice($response['message'], 'error');
        return ['result' => 'failure'];
    }

    $order->update_meta_data('_mypay_payment_id', $response['payment_id']);
    $order->save();

    return [
        'result'   => 'success',
        'redirect' => $response['payment_url'],
    ];
}

Обробка webhook

Webhook-адреса: https://site.com/?wc-api=mypay_callback

public function handle_webhook(): 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'] ?? '')) {
        wp_die('Invalid signature', 'Forbidden', ['response' => 403]);
    }

    $order = wc_get_orders([
        'meta_key'   => '_mypay_payment_id',
        'meta_value' => $data['payment_id'],
        'limit'      => 1,
    ])[0] ?? null;

    if (!$order) {
        wp_die('Order not found', '', ['response' => 404]);
    }

    match ($data['status']) {
        'succeeded' => $order->payment_complete($data['payment_id']),
        'failed'    => $order->update_status('failed', 'Платіж відхилений: ' . $data['reason']),
        'refunded'  => $order->update_status('refunded'),
        default     => null,
    };

    wp_die('OK', '', ['response' => 200]);
}

Повернення у WooCommerce

Підтримка повернень додається через метод process_refund:

public function process_refund(int $order_id, ?float $amount = null, string $reason = ''): bool|\WP_Error
{
    $order      = wc_get_order($order_id);
    $payment_id = $order->get_meta('_mypay_payment_id');

    if (!$payment_id) {
        return new \WP_Error('mypay_refund', 'Payment ID не знайдено');
    }

    $client   = new MyPay_API_Client($this->api_key, $this->secret_key, $this->testmode);
    $response = $client->refund($payment_id, (int) ($amount * 100), $reason);

    if ($response['status'] === 'error') {
        return new \WP_Error('mypay_refund', $response['message']);
    }

    $order->add_order_note(sprintf('Повернення %s RUB через MyPay. ID: %s', $amount, $response['refund_id']));
    return true;
}

Після цього кнопка «Вернути» в admin-панелі WooCommerce викликає цей метод автоматично.

Тестування

WooCommerce має вбудований тестовий режим. Для тестування webhook використовується ngrok або localtunnel — провайдер повинен мати можливість добратися до localhost. Всі тестові номери карт беруться з документації конкретного шлюзу.