Интеграция CloudPayments на сайт: от виджета до API

Интеграция платежей — узкое место, где теряется до 15% заказов. Покупатели бросают корзину, если форма уводит на сторонний сайт или долго грузится. CloudPayments решает это встроенным виджетом: пользователь не покидает страницу. В одном из проектов — интернет-магазин электроники с оборотом $14k–20k в месяц — после перехода с редиректа на виджет конверсия выросла на 12%. Типичная потеря от отказов до интеграции составляла $4.5k–6.5k в месяц. CloudPayments позволяет удержать клиента, и мы накопили опыт для 20+ проектов. Гарантируем стабильную работу и полную фискализацию по 54-ФЗ.

Как CloudPayments повышает конверсию?

Виджет CloudPayments — всплывающая форма поверх сайта. Скрипт ~180 КБ, загружается лениво. В наших проектах конверсия выросла в среднем на 10% после перехода с уводящей страницы. Сравнение с Checkout (iframe) — виджет даёт на 5–7% больше завершённых транзакций за счёт меньшего числа шагов. При этом дополнительная выручка достигает $1.8k–2.6k в месяц для магазина со средним чеком $27–39 и 1000 заказов.

Какие проблемы решаем?

• Конверсия — платёжная форма поверх сайта без редиректа повышает LTV и снижает отток. Каждый дополнительный шаг отсекает часть покупателей. Виджет минимизирует эти потери.
• Безопасность — 3D Secure 2.0, сертификация PCI DSS Level 1, токенизация карт. CloudPayments проходит ежегодный аудит безопасности — вам не нужно заботиться о хранении чувствительных данных.
• Законность — встроенная онлайн-касса с автоматической передачей чеков в ОФД. Все операции соответствуют 54-ФЗ, штрафы за отсутствие чеков исключены.
• Гибкость — рекуррентные платежи для подписок, возвраты полные/частичные, мультивалютность. CloudPayments поддерживает USD, USD, EUR — можно принимать платежи из-за рубежа.

Как мы подключаем CloudPayments?

Мы используем виджет как самый быстрый способ (1-2 дня) с конверсией выше, чем при iframe. Для полного кастома UI — API (5-10 дней, требует PCI DSS SAQ A-EP). Для типовых задач хватает виджета.

Сравнение виджета и API для кастомизации

Подключение виджета

<script src="https://widget.cloudpayments.ru/bundles/cloudpayments.js"></script> 

const pay = () => {
  const widget = new cp.CloudPayments({ language: 'ru-RU' });
  widget.charge(
    {
      publicId: 'pk_xxxxxxxxxxxxxxxxxxxx',
      description: 'Заказ #12345',
      amount: 1500,
      currency: 'USD',
      accountId: '[email protected]',
      invoiceId: 'order-12345',
      skin: 'mini',
      data: {
        orderId: 12345,
      },
    },
    (options) => {
      console.log('payment success', options);
    },
    (reason, options) => {
      console.error('payment failed:', reason);
    },
  );
};

publicId — публичный ключ из личного кабинета. Секретный ключ (apiSecret) — только на сервере, никогда во фронтенде.

Как проверить HMAC-подпись webhook?

1. Получите тело POST-запроса от CloudPayments.
2. Вычислите HMAC SHA256 от тела, используя секретный ключ (apiSecret).
3. Сравните полученную подпись с заголовком Content-HMAC.
4. Если не совпадает — верните HTTP 403.
5. При совпадении обработайте статус платежа.

После оплаты CloudPayments отправляет POST на URL, указанный в личном кабинете (раздел «Уведомления»). Тип уведомления — payment. Для проверки используется HMAC SHA256, описанный в стандарте. Подробнее — в официальной документации CloudPayments.

public function handleWebhook(Request $request): Response
{
    $hmac = base64_encode(
        hash_hmac('sha256', $request->getContent(), env('CP_API_SECRET'), true)
    );

    if ($hmac !== $request->header('Content-HMAC')) {
        return response('Invalid signature', 403);
    }

    $data = $request->all();

    if ($data['Status'] === 'Completed') {
        $orderId = $data['InvoiceId'];
        $amount = $data['Amount'];

        Order::where('id', $orderId)
            ->where('total', $amount)
            ->update(['status' => 'paid', 'transaction_id' => $data['TransactionId']]);
    }

    return response()->json(['code' => 0]);
}

Если вернуть {"code": 13}, CloudPayments будет повторять уведомление по расписанию до 10 раз. Это полезно при временных ошибках БД.

Как настроить фискализацию по 54-ФЗ?

CloudPayments имеет встроенную онлайн-кассу. Данные для чека передаются в параметре cloudPayments.customerReceipt внутри объекта data виджета:

data: {
  cloudPayments: {
    customerReceipt: {
      Items: [
        {
          label: 'Товар 1',
          price: 1500.00,
          quantity: 1.0,
          amount: 1500.00,
          vat: null,
          method: 0,
          object: 1,
        },
      ],
      taxationSystem: 1,
      email: '[email protected]',
      amounts: {
        electronic: 1500.00,
        advancePayment: 0.00,
        credit: 0.00,
        provision: 0.00,
      },
    },
  },
}

Для повторных платежей без ввода реквизитов CloudPayments возвращает Token в первом успешном платеже. Его сохраняют в БД и используют для последующих списаний:

$response = Http::withBasicAuth(env('CP_PUBLIC_ID'), env('CP_API_SECRET'))
    ->post('https://api.cloudpayments.ru/payments/tokens/charge', [
        'Amount' => 1500,
        'Currency' => 'USD',
        'AccountId' => '[email protected]',
        'Token' => $savedToken,
        'InvoiceId' => 'order-12346',
        'Description' => 'Автоматическое списание',
    ]);

Возвраты выполняются через API: передайте TransactionId и сумму частичного возврата. CloudPayments поддерживает как полные, так и частичные возвраты.

Этапы работы

Что входит в результаты

• Настройка личного кабинета CloudPayments: домен, webhook, публичный/секретный ключи.
• Встраивание виджета с поддержкой рекуррентов и фискализации.
• Разработка серверного webhook с валидацией HMAC-подписи.
• Интеграция возвратов и токенизации.
• Документация и обучение сотрудников работе с платёжным модулем.

Почему выбирают нас

• 5+ лет опыта разработки и интеграции платёжных систем.
• 20+ успешных проектов с CloudPayments.
• Сертифицированные специалисты.
• Поддержка после сдачи: отладка, доработки, мониторинг.

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