Платежи — это сердце любого онлайн-бизнеса. Но когда дело доходит до интеграции с платежными системами, многие разработчики начинают паниковать. Я сам через это прошел, поэтому расскажу, как подключить Yii2 к популярным платежкам без лишней боли.

Digital-студия WNDER

В этой статье я поделюсь опытом, покажу рабочие примеры кода и дам советы, которые сэкономят вам часы дебагов. Поехали!

Почему Yii2 и платежные системы — это сложно?

Yii2 — мощный фреймворк, но у него нет встроенного модуля для платежей. Каждая платежная система (ЮKassa, Stripe, PayPal, СБП и другие) имеет свои API, свои форматы запросов и свои подводные камни. Если вы новичок, легко запутаться в документации и потерять кучу времени.

Основные сложности:

  • Разные форматы данных (JSON, XML, form-data)
  • Разные способы аутентификации (ключи, токены, подписи)
  • Обработка уведомлений (callback) — нужно правильно принимать и отвечать
  • Безопасность — нельзя допустить, чтобы кто-то подделал запрос

Но не бойтесь. Все решаемо, если действовать по плану.

Выбор платежной системы: что учесть

Перед тем как писать код, определитесь, какую систему вы будете подключать. Я советую выбирать ту, которая:

  • Поддерживает вашу страну и валюту
  • Имеет простой API и хорошую документацию
  • Предоставляет готовые SDK для PHP (это упростит жизнь)
  • Берет адекватную комиссию

Вот таблица популярных систем и их особенностей:

Система Форматы Аутентификация Сложность интеграции
ЮKassa (Яндекс.Касса) JSON API-ключ + токен Средняя
Stripe JSON Secret key Низкая
PayPal JSON Client ID + Secret Средняя
СБП (Сбербанк) XML Сертификаты Высокая

Если вы только начинаете, берите Stripe или ЮKassa — у них отличные SDK и примеры.

Создание платежного модуля: структура

В Yii2 я рекомендую вынести всю логику платежей в отдельный компонент. Так код будет чистым и переиспользуемым. Создадим компонент PaymentService в папке components.

<?php
namespace app\components;

use Yii;
use yii\base\Component;

class PaymentService extends Component
{
    public $gateway; // объект платежного шлюза

    public function init()
    {
        parent::init();
        // Инициализация шлюза на основе конфигурации
        $this->gateway = new \YandexCheckout\Client();
        $this->gateway->setAuth(
            Yii::$app->params['payment.shopId'],
            Yii::$app->params['payment.secretKey']
        );
    }

    public function createPayment($amount, $description, $metadata = [])
    {
        $payment = $this->gateway->createPayment(
            [
                'amount' => [
                    'value' => $amount,
                    'currency' => 'RUB',
                ],
                'confirmation' => [
                    'type' => 'redirect',
                    'return_url' => Yii::$app->urlManager->createAbsoluteUrl(['payment/success']),
                ],
                'description' => $description,
                'metadata' => $metadata,
            ],
            uniqid('', true)
        );

        return $payment;
    }
}
?>

В конфигурационном файле config/params.php добавьте ключи:

<?php
return [
    'payment.shopId' => '123456',
    'payment.secretKey' => 'test_secret',
];

Теперь в любом контроллере можно вызвать:

$paymentService = Yii::$app->paymentService;
$payment = $paymentService->createPayment(100, 'Тестовый заказ', ['order_id' => 123]);

Создание платежа: пример контроллера

Теперь создадим контроллер для обработки платежей. Он будет создавать платеж и перенаправлять пользователя на страницу оплаты.

<?php
namespace app\controllers;

use Yii;
use yii\web\Controller;
use app\models\Order;

class PaymentController extends Controller
{
    public function actionCreate($orderId)
    {
        $order = Order::findOne($orderId);
        if (!$order) {
            throw new \yii\web\NotFoundHttpException('Заказ не найден');
        }

        $paymentService = Yii::$app->paymentService;
        $payment = $paymentService->createPayment(
            $order->total,
            'Оплата заказа #' . $order->id,
            ['order_id' => $order->id]
        );

        // Сохраняем id платежа в заказе
        $order->payment_id = $payment->id;
        $order->save();

        // Перенаправляем на страницу оплаты
        return $this->redirect($payment->confirmation->confirmation_url);
    }
}

Важно: confirmation_url — это ссылка, которую предоставляет платежная система для перехода пользователя на платежную страницу. Не пытайтесь генерировать ее сами.

Обработка уведомлений (callback)

После оплаты платежная система отправляет уведомление на ваш сервер. Это называется callback или webhook. В Yii2 нужно создать действие, которое будет принимать эти уведомления.

public function actionCallback()
{
    $source = file_get_contents('php://input');
    $data = json_decode($source, true);

    // Проверяем подпись или токен (зависит от системы)
    if (!$this->validateCallback($data)) {
        Yii::error('Неверная подпись callback', 'payment');
        return 'error';
    }

    // Обрабатываем событие
    if ($data['event'] === 'payment.succeeded') {
        $paymentId = $data['object']['id'];
        $order = Order::find()->where(['payment_id' => $paymentId])->one();
        if ($order && $order->status === Order::STATUS_PENDING) {
            $order->status = Order::STATUS_PAID;
            $order->save();
        }
    }

    // Отвечаем системе, что все ок
    return 'OK';
}

Не забудьте отключить проверку CSRF для этого действия, иначе Yii2 не пропустит запрос:

public function beforeAction($action)
{
    if ($action->id === 'callback') {
        $this->enableCsrfValidation = false;
    }
    return parent::beforeAction($action);
}
Лайфхак: Всегда логируйте входящие callback-запросы. Даже если они кажутся подозрительными. Это поможет вам отладить интеграцию и выявить проблемы на ранних стадиях.

Безопасность: защита от подделки

Самое важное — проверять подлинность запросов от платежной системы. Если этого не делать, злоумышленник может отправить фейковый callback и пометить заказ как оплаченный, не заплатив ни копейки.

Каждая система предлагает свой способ проверки:

  • ЮKassa — проверка IP-адреса отправителя и подписи в заголовках
  • Stripe — проверка подписи с помощью вебхук-секрета
  • PayPal — проверка через IPN-сообщение (обратный запрос)

Пример проверки для ЮKassa:

private function validateCallback($data)
{
    // Проверяем IP
    $validIps = ['185.71.76.0/27', '185.71.77.0/27', '77.75.153.0/25', '77.75.154.128/25'];
    $ip = Yii::$app->request->userIP;
    if (!$this->ipInRange($ip, $validIps)) {
        return false;
    }

    // Проверяем, что объект платежа существует
    if (empty($data['object']['id'])) {
        return false;
    }

    return true;
}

Для Stripe используйте библиотеку для проверки подписи:

\Stripe\Webhook::constructEvent(
    $payload,
    $sigHeader,
    $endpointSecret
);

Работа с тестовым режимом

Перед запуском в продакшн обязательно протестируйте интеграцию. Практически все платежные системы предоставляют тестовые ключи и песочницу.

В тестовом режиме используйте тестовые карты (например, 5555 5555 5555 4444 для Stripe). Не пытайтесь использовать реальные карты — это может привести к блокировке аккаунта.

Правило: Никогда не отправляйте реальные платежи в тестовой среде. Это не только опасно, но и может привести к финансовым потерям.

Заключение

Интеграция Yii2 с платежными системами — задача решаемая. Главное — подойти к ней системно:

  • Выберите подходящую платежную систему
  • Создайте компонент для работы с API
  • Реализуйте создание платежей и обработку callback
  • Позаботьтесь о безопасности
  • Протестируйте все в песочнице

В итоге вы получите надежный платежный модуль, который будет работать без сбоев. А если что-то пойдет не так — не бойтесь читать документацию и логи. Там всегда есть ответ.

Удачи в разработке!

Студия WNDER