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

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

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

Підвищення конверсії з CloudPayments

Віджет CloudPayments — спливаюча форма поверх сайту. Скрипт ~180 КБ, завантажується ліниво. У наших проектах конверсія зросла в середньому на 10% після переходу зі сторінки, що відводить. Віджет кращий за Checkout в 1.05–1.07 разів за конверсією завдяки меншій кількості кроків. При цьому додатковий виторг досягає $1.8k–2.6k на місяць для магазину із середнім чеком $27–39 і 1000 замовлень. Крім того, налаштування фіскалізації через віджет займає в 2-3 рази менше часу, ніж через API.

Вирішення ключових проблем

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

Наш підхід до підключення

Ми використовуємо віджет як найшвидший спосіб (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: 'uk-UA' });
  widget.charge(
    {
      publicId: 'pk_xxxxxxxxxxxxxxxxxxxx',
      description: 'Замовлення #12345',
      amount: 1500,
      currency: 'UAH',
      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]);
}

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,
      },
    },
  },
}

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