Интеграция CloudPayments на самописный сайт: полное руководство

CloudPayments интегрируется на самописный сайт в России через настройку API-ключей и создание обработчика instant payment notifications (IPN). Основные сложности возникают из-за недостатка практических примеров в официальной документации, но функциональность доступна через GitHub-репозитории и руководства от других разработчиков.

Содержание

• Официальная документация и ресурсы
• Настройка IPN (instant payment notifications)
• Примеры кода для интеграции
• Интеграция t-kassa
• Решение типичных проблем
• Лучшие практики безопасности

Официальная документация и ресурсы

Основным источником информации служит официальная документация CloudPayments для разработчиков. Несмотря на то, что в ней представлены только списки API-функций, это базовый ресурс для понимания структуры взаимодействия.

Ключевые элементы для интеграции:

• Public ID - публичный идентификатор вашего аккаунта
• API Password - секретный ключ для подписи запросов
• URL для IPN-уведомлений - адрес вашего сервера для обработки платежей

Для самописного сайта необходимо создать обработчик платежей, который будет:

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

Важно: В личном кабинете CloudPayments нужно указать адрес для Pay уведомлений в формате http://ваш-сайт/обработчик.php с методом POST и кодировкой Windows-1251, как указано в документации PHPShop.

Настройка IPN (instant payment notifications)

IPN-уведомления являются критически важным элементом интеграции, так как именно через них вы получаете информацию о статусе платежей.

Основные шаги настройки IPN:

1. Создайте обработчик на вашем сервере (например, ipn_handler.php)

2. Настройте прием POST-запросов от CloudPayments

3. Реализуйте проверку HMAC-подписи для безопасности

4. Обработайте различные статусы платежей:

   • Success (успешный платеж)
   • Fail (неудачный платеж)
   • Partial (частичный платеж)

Базовый пример структуры IPN-обработчика на PHP:

<?php
// Получаем данные от CloudPayments
$rawData = file_get_contents('php://input');
$notificationData = json_decode($rawData, true);

// Проверяем HMAC-подпись
$publicId = 'ваш_public_id';
$apiKey = 'ваш_api_key';
$receivedSignature = $_SERVER['HTTP_AUTHORIZATION'] ?? '';

// Рассчитываем нашу подпись
$calculatedSignature = base64_encode(hash_hmac('sha256', $rawData, $apiKey, true));

if ($receivedSignature === 'Basic ' . $calculatedSignature) {
    // Подпись верна, обрабатываем уведомление
    $invoiceId = $notificationData['InvoiceId'] ?? '';
    $amount = $notificationData['Amount'] ?? 0;
    $status = $notificationData['Status'] ?? '';
    
    // Обновляем статус заказа в вашей системе
    updateOrderStatus($invoiceId, $status);
    
    // Отправляем подтверждение
    http_response_code(200);
    echo json_encode(['Success' => true]);
} else {
    // Подпись неверна, игнорируем запрос
    http_response_code(403);
    echo json_encode(['Error' => 'Invalid signature']);
}

Примеры кода для интеграции

JavaScript/Node.js пример

Из GitHub-репозитория доступен пример на Node.js:

import {createServer} from 'http';
import {ClientService, TaxationSystem, ResponseCodes} from 'cloudpayments';

const client = new ClientService({
    privateKey: 'private key',
    publicId: 'public id',
    org: {
        taxationSystem: TaxationSystem.GENERAL,
        inn: 123456789
    }
});

const handlers = client.getNotificationHandlers();
const server = createServer(async (req, res) => {
    if (req.url == '/cloudpayments/fail') {
        const response = await handlers.handleFailRequest(req, async (request) => {
            // Обрабатываем информацию о неудачном платеже
            return ResponseCodes.SUCCESS;
        });
        res.setHeader('Content-Type', 'application/json');
        res.end(JSON.stringify(response));
    }
});

server.listen(3000, () => {
    console.log('Server running on port 3000');
});

PHP клиентская библиотека

Официальная PHP-библиотека CloudPayments предоставляет удобный интерфейс для работы с API:

<?php
require_once 'vendor/autoload.php';

use CloudPayments\Manager;
use CloudPayments\Model\Request\Payment\Card;

$manager = new Manager(
    'your_public_id',
    'your_api_password'
);

// Создание платежа
$response = $manager->paymentCards()->post([
    'Amount' => 10.00,
    'Currency' => 'RUB',
    'IpAddress' => '192.168.0.1',
    'Name' => 'Иванов Иван',
    'CardCryptogramPacket' => 'eyJoYXNoIjoiNDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0IiwiaHR0cHM6Ly9hdXRoLmNsb3VkYXBwbGVzLmNvbS9hcGkvY2FyZHMvY2FyZHMtcGF5bWVudC8iLCJ0eXBlIjoiUEFTU1dPUkQiLCJ2ZXJzaW9uIjoxfQ==',
    'Description' => 'Оплата товара №123',
    'InvoiceId' => 'ORDER-123',
    'Email' => 'customer@example.com'
]);

WordPress интеграция

Из руководства Misha Agency доступен пример для WordPress:

<?php
// Файл 3ds.php для обработки 3DS аутентификации
$publicID = 'ПУБЛИЧНЫЙ_API_КЛЮЧ';
$apiKey = 'СЕКРЕТНЫЙ_API_КЛЮЧ';

// Обрабатываем платёж после ввода кода подтверждения
$response = wp_remote_post('https://api.cloudpayments.ru/payments/cards/post3ds', array(
    'method' => 'POST',
    'timeout' => 45,
    'headers' => array(
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
        'Authorization' => 'Basic ' . base64_encode($publicID . ':' . $apiKey)
    ),
    'body' => json_encode($paymentData)
));

Интеграция t-kassa

t-kassa представляет собой упрощенную версию CloudPayments с меньшим функционалом. Основные отличия:

1. Меньше настроек - нет сложных параметров налоговых систем
2. Упрощенный API - методы более базовые
3. Ограниченные возможности - некоторые функции недоступны

Типичные проблемы при интеграции t-kassa:

• Отсутствие полноценной документации
• Сложности с получением технической поддержки
• Ограниченные возможности по кастомизации платежной формы

Если вы столкнулись с необходимостью использовать t-kassa, рекомендую:

1. Начать с интеграции полноценной версии CloudPayments
2. В случае необходимости перейти на t-kassa как более простую альтернативу
3. Адаптировать код для работы с упрощенным API

Решение типичных проблем

Проблема: Нет практических примеров в документации

Решение: Используйте следующие ресурсы:

• 1С-Битрикс модуль CloudPayments - изучение исходного кода модуля
• Интеграция с Tilda - адаптация примеров под вашу систему
• Руководство по Webasyst - универсальные подходы к интеграции

Проблема: HMAC-проверка не работает

Решение: Убедитесь, что:

1. Используется правильный алгоритм (SHA256)
2. Ключ API не содержит лишних пробелов
3. Данные для подписи не изменяются между расчетом и проверкой

Проблема: Не приходят уведомления

Решение:

1. Проверьте доступность вашего IPN-обработчика из интернета
2. Убедитесь, что сервер корректно обрабатывает POST-запросы
3. Проверьте логи CloudPayments на наличие ошибок

Лучшие практики безопасности

1. Всегда проверяйте HMAC-подпись перед обработкой уведомлений
2. Используйте HTTPS для всех коммуникаций с вашим сервером
3. Храните API-ключи в защищенном месте (не в репозитории Git)
4. Реализуйте логирование всех уведомлений для отладки
5. Ограничьте доступ к IPN-обработчику IP-адресами CloudPayments

Важно: Согласно рекомендациям безопасности, всегда используйте HTTPS для шифрования данных между платежным шлюзом и вашим сервером, а также реализуйте проверку HMAC-подписи для целостности данных.

Источники

1. Официальная документация CloudPayments для разработчиков
2. CloudPayments PHP Client Library на GitHub
3. Пример интеграции на JavaScript/Node.js
4. Инструкция по интеграции CloudPayments в PHPShop
5. Руководство по подключению CloudPayments в WordPress
6. Платежный модуль для 1С-Битрикс
7. Подключение CloudPayments в Tilda
8. Интеграция CloudPayments с Webasyst

Заключение

Интеграция CloudPayments на самописный сайт в России требует времени и внимания к деталям, но полностью реализуема. Основные рекомендации:

1. Начните с изучения официальной документации и GitHub-репозиториев
2. Реализуйте надежный IPN-обработчик с проверкой HMAC-подписи
3. Тестируйте интеграцию в тестовом режиме перед запуском в продакшн
4. Используйте готовые примеры кода из различных источников и адаптируйте их под ваши нужды
5. При возникновении сложностей с t-kassa, рассмотрите возможность использования полноценной версии CloudPayments

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