Инструкция по интеграции приема платежей в Cotonti

Эта инструкция предназначена для разработчиков, создающих расширения электронной коммерции (например, интернет-магазины, платные услуги или консультации) для платформы Cotonti. Она подробно описывает, как организовать прием платежей с помощью модуля Payments, включая интеграцию с платежными системами, создание собственного платежного плагина, обработку вебхуков и тестирование. Руководство написано понятно, с четкой структурой и примерами.

Обзор модуля Payments

Модуль Payments в Cotonti — универсальный инструмент для организации приема платежей в расширениях. Он поддерживает интеграцию с различными платежными системами, такими как PayPal, Payeer, Unitpay, Enot, Robokassa, банковские и криптовалютные системы, а также другие.  Модуль позволяет создавать платежи, обрабатывать их статусы и перенаправлять пользователей на страницы оплаты. После оплаты модуль вызывает хук для обработки статуса, что позволяет расширению автоматически активировать оплаченные услуги.

Основные возможности модуля

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

Создание платежа в расширении

Подготовка к созданию платежа

Для реализации приема платежей в вашем расширении (например, интернет-магазине или сервисе платных услуг) необходимо использовать функцию cot_payments_create_order(). Она создает платеж в системе Cotonti и перенаправляет пользователя на страницу выбора платежной системы.

Пример кода для создания платежа в контроллере вашего расширения после формирования заказа:

$amount = 500; // Сумма платежа (в рублях, копейки — дробная часть, например, 500.00)
$area = 'orderType'; // Тип платежа (например, 'order' для заказа или 'service' для услуги)
$options = [
    // Необязательно. Срок действия оплаченной услуги (в секундах).
    'time' => $months * 30 * 24 * 60 * 60, // Например, 1 месяц = 30 дней
    
    // Необязательно. Описание платежа.
    'desc' => 'Оплата заказа №123',
    
    // Необязательно. Идентификатор заказа или пользователя в вашем расширении.
    'code' => $orderId,
    
    // Необязательно. URL для перенаправления после успешной оплаты.
    'redirect' => cot_url('extension-code', ['m' => 'orders', 'id' => $orderId], '', true)
];

cot_payments_create_order($area, $amount, $options);

Пояснения к параметрам

• $amount: Сумма платежа. Указывается в валюте, поддерживаемой платежной системой. Копейки передаются как дробная часть (например, 500.50 для 500 рублей 50 копеек).
• $area: Тип платежа. Используется для идентификации в вашей системе (например, 'order' для заказов или 'subscription' для подписок). Вместе с $options['code'] должно уникально идентифицировать платеж.
• $options['time']: Срок действия услуги (например, для подписок). Указывается в секундах.
• $options['desc']: Описание платежа, которое увидит пользователь.
• $options['code']: Уникальный идентификатор заказа или пользователя в вашем расширении.
• $options['redirect']: URL, на который перенаправляется пользователь после успешной оплаты. Если не указан, пользователь попадет на страницу истории платежей (https://domain.tld/payments?m=balance&n=history).

Обработка платежа после оплаты

После успешной оплаты платежная система уведомляет Cotonti через вебхук, и модуль Payments меняет статус платежа на "Оплачен". В этот момент вызывается хук payments.payment.success, который ваше расширение должно обработать для активации оплаченной услуги.

Пример обработки хука:

// Файл: plugins/yourExtension/yourExtension.payments.payment.success.php
global $db, $db_payments;

if (cot_module_active('payments')) {
    // Получаем данные платежа
    $payment = $params; // $params — массив с данными из таблицы cot_payments
    
    // Проверяем, что платеж относится к вашему расширению
    if ($payment['pay_area'] === 'orderType' && !empty($payment['pay_code'])) {
        // Здесь ваша логика активации услуги
        // Например, обновление статуса заказа в базе данных
        $db->update($db_orders, ['order_status' => 'paid'], "order_id = ?", [$payment['pay_code']]);
    }
}

Важно: Хук payments.payment.success вызывается сервером платежной системы через вебхук, поэтому в нем нельзя выводить данные, заголовки или выполнять редиректы. Для вывода информации пользователю используйте страницу, указанную в $options['redirect'].

Тестирование с плагином Nullbilling

Для проверки интеграции вашего расширения с модулем Payments используйте плагин Nullbilling. Это тестовая платежная система, которая имитирует успешную оплату без реальных транзакций.

Шаги для тестирования

1. Установите плагин Nullbilling через админ-панель Cotonti.
2. Создайте тестовый заказ в вашем расширении, используя код выше.
3. Перейдите на страницу оплаты, выберите Nullbilling как платежную систему.
4. Подтвердите "оплату" — плагин сэмулирует успешный платеж.
5. Убедитесь, что хук payments.payment.success сработал и услуга активировалась (например, статус заказа изменился).

Создание собственного плагина платежной системы

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

Регистрация платежной системы

Плагин должен зарегистрироваться в массиве $cot_billings через хук payments.billing.register. Пример:

// Файл: plugins/myPaymentSystem/myPaymentSystem.payments.billing.register.php
if (
    Cot::$cfg['plugin']['myPaymentSystem']['on']
    && !empty(Cot::$cfg['plugin']['myPaymentSystem']['apiKey'])
    && !empty(Cot::$cfg['plugin']['myPaymentSystem']['secret'])
) {
    $cot_billings['myPaymentSystem'] = [
        'plug' => 'myPaymentSystem',
        'title' => Cot::$L['myPaymentSystem_title'], // Название системы, например, "Моя платежная система"
        'icon' => Cot::$cfg['plugins_dir'] . '/myPaymentSystem/images/logo.png',
    ];
}

Пояснения

• Проверяем, что плагин включен и настроены ключи API.
• plug: Код плагина (должен совпадать с именем папки плагина).
• title: Название платежной системы, отображаемое пользователю.
• icon: Путь к логотипу платежной системы.

Отключение Anti-XSS для вебхуков

Если платежная система отправляет уведомления (вебхуки) методом POST, необходимо отключить защиту Anti-XSS для обработчика вебхука, чтобы Cotonti принял запрос. Это делается через хук input:

// Файл: plugins/myPaymentSystem/myPaymentSystem.input.php
if (
    isset($_GET['e'])
    && $_GET['e'] === 'myPaymentSystem'
    && isset($_GET['a'])
    && $_GET['a'] === 'notify'
    && $_SERVER['REQUEST_METHOD'] === 'POST'
) {
    define('COT_NO_ANTIXSS', 1);
    Cot::$cfg['referercheck'] = false;
}

Пояснения

• Проверяем параметры запроса (e и a) и метод (POST).
• Отключаем Anti-XSS и проверку реферера для вебхука.

Удаление кнопки "Открыть" в админ-панели

Платежные плагины не используют standalone-страницу для вывода данных пользователю, поэтому кнопку "Открыть" в админ-панели можно убрать. Это делается через хуки admin.extensions.plug.list.loop и admin.extensions.details:

// Файл: plugins/myPaymentSystem/myPaymentSystem.admin.extensions.plug.list.loop.php
if ($type === COT_EXT_TYPE_PLUGIN && $code === 'myPaymentSystem') {
    $t->assign([
        'ADMIN_EXTENSIONS_JUMPTO_URL' => null,
    ]);
}

// Файл: plugins/myPaymentSystem/myPaymentSystem.admin.extensions.details.php
if ($type === COT_EXT_TYPE_PLUGIN && $code === 'myPaymentSystem') {
    $standalone = null;
    $t->assign([
        'ADMIN_EXTENSIONS_JUMPTO_URL' => $standalone,
    ]);
}

Вывод справочной информации в админ-панели

Если в админ-панели нужно показать инструкции по настройке плагина (например, как получить API-ключи в личном кабинете платежной системы), используйте хук admin.config.edit.tags:

// Файл: plugins/myPaymentSystem/myPaymentSystem.admin.config.edit.tags.php
if ($o === COT_EXT_TYPE_PLUGIN && $p === 'myPaymentSystem') {
    $adminHelp = 'Для настройки платежной системы войдите в личный кабинет на сайте myPaymentSystem.com, получите API-ключ и секретный ключ, затем укажите их в настройках плагина.';
}

Обработка standalone-хука

Хук standalone обрабатывает два сценария:

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

Пример кода для хука standalone:

// Файл: plugins/myPaymentSystem/myPaymentSystem.standalone.php
require_once cot_incfile('payments', 'module');

// Получаем ID платежа
$paymentId = cot_import('pid', 'G', 'INT');
if ($paymentId) {
    // Сценарий 1: Перенаправление на оплату
    $payment = PaymentRepository::getById($paymentId);
    if (!$payment) {
        cot_die_message(404);
    }

    // Проверяем, что платеж можно оплатить
    cot_block(in_array($payment['pay_status'], PaymentDictionary::ALLOW_PAYMENT_STATUSES, true));

    // Генерируем уникальный ID для платежной системы, если требуется
    $psPaymentId = $paymentId . '-' . time();

    // Формируем запрос к API платежной системы
    $apiKey = Cot::$cfg['plugin']['myPaymentSystem']['apiKey'];
    $secret = Cot::$cfg['plugin']['myPaymentSystem']['secret'];
    $paymentData = [
        'amount' => $payment['pay_summ'],
        'description' => $payment['pay_desc'],
        'order_id' => $psPaymentId,
        'success_url' => PaymentService::getSuccessUrl($paymentId),
        'fail_url' => PaymentService::getFailUrl($paymentId),
    ];

    // Пример отправки запроса к API (зависит от платежной системы)
    $response = sendApiRequest($apiKey, $secret, $paymentData); // Ваша функция для API

    if ($response['status'] === 'success' && !empty($response['payment_url'])) {
        // Устанавливаем статус "В процессе"
        PaymentService::setStatus(
            $paymentId,
            PaymentDictionary::STATUS_PROCESS,
            'myPaymentSystem',
            PaymentDictionary::METHOD_CARD,
            $psPaymentId
        );
        // Перенаправляем пользователя на страницу оплаты
        cot_redirect($response['payment_url']);
    } else {
        cot_die_message(500, 'Ошибка инициализации платежа');
    }
}

// Сценарий 2: Обработка вебхука
if (isset($_GET['a']) && $_GET['a'] === 'notify' && $_SERVER['REQUEST_METHOD'] === 'POST') {
    $webhookData = json_decode(file_get_contents('php://input'), true); // Пример для JSON
    $paymentId = $webhookData['payment_id']; // ID платежа из Cotonti
    $transactionId = $webhookData['transaction_id']; // ID транзакции в платежной системе

    // Проверяем подпись или другие параметры согласно документации платежной системы
    if (verifyWebhook($webhookData, Cot::$cfg['plugin']['myPaymentSystem']['secret'])) {
        // Устанавливаем статус "Оплачен"
        PaymentService::setStatus(
            $paymentId,
            PaymentDictionary::STATUS_PAID,
            'myPaymentSystem',
            null,
            null,
            $transactionId
        );
    }
    exit; // Завершаем выполнение, не выводим данные
}

Пояснения

• Сценарий 1 (перенаправление): Проверяем ID платежа, получаем данные из таблицы cot_payments, отправляем запрос к API платежной системы для инициализации платежа. После получения URL оплаты устанавливаем статус "В процессе" и перенаправляем пользователя.
• Сценарий 2 (вебхук): Обрабатываем уведомление от платежной системы. Проверяем подпись или другие параметры, затем обновляем статус платежа в Cotonti. Никаких данных не выводим, так как запрос идет от сервера платежной системы.
• Функции sendApiRequest и verifyWebhook — условные, их нужно реализовать согласно документации вашей платежной системы.

Полезные советы

1. Уникальный ID платежа: Если платежная система требует уникальный ID для каждого запроса, генерируйте его, комбинируя ID платежа Cotonti и временную метку (например, $paymentId . '-' . time()).
2. Логирование: Добавьте логирование в обработчик вебхуков для отладки (например, в файл или базу данных), чтобы отслеживать входящие запросы и ошибки.
3. Тестирование вебхуков: Используйте инструменты вроде Postman или ngrok для тестирования вебхуков на локальном сервере.
4. Документация API: Внимательно изучите документацию платежной системы для корректной реализации запросов и проверки вебхуков.
5. Безопасность: Всегда проверяйте подписи вебхуков, чтобы избежать поддельных запросов.

Итог

Модуль Payments в Cotonti предоставляет гибкий и удобный способ интеграции платежных систем в ваши расширения. Создание платежей через cot_payments_create_order() и обработка хука payments.payment.success позволяют автоматизировать активацию услуг. Для подключения новой платежной системы создайте плагин, зарегистрируйте его в $cot_billings, настройте обработку вебхуков и протестируйте с помощью Nullbilling. Следуя этой инструкции, вы сможете быстро и надежно организовать прием платежей в вашем проекте.

Обсуждение модуля, вопросы и помощь  в разделе форума.