Інтеграція 1С-Бітрікс із платіжною системою PayKeeper

Інтеграція 1С-Бітрікс із платіжною системою PayKeeper

Інтеграція платіжного шлюзу PayKeeper з 1С-Бітрікс — завдання, з яким стикається кожен, хто хоче отримати повний контроль над платежами. Без правильної обробки сповіщень та фіскалізації магазин ризикує втратити гроші та отримати штраф. Ми вирішуємо цю проблему на проєктах з 2018 року: за 5 років реалізували понад 30 інтеграцій — від інтернет-магазинів до B2B-порталів.

Нещодавно ми впроваджували PayKeeper для магазину з 10 000 замовлень на місяць. Вимагалася повна фіскалізація за 54-ФЗ та обробка повернень. Результат: час оплати скоротився до 15 секунд, а комісія виявилася значно нижчою, ніж у деяких інших систем.

Як працює PayKeeper?

PayKeeper — це PHP-додаток, який працює як платіжний сервер на вашому домені або в хмарі. Магазин через API створює рахунок, отримує URL форми оплати, покупець вводить дані картки. Сповіщення про оплату приходять на result_url. Як зазначено в документації PayKeeper, всі запити захищені MD5-підписом.

Формування інвойсу через API

$apiUrl = $this->getBusinessValue($payment, 'PAYKEEPER_URL'); // https://your.paykeeper.ru $clientId = $this->getBusinessValue($payment, 'PAYKEEPER_USER'); $clientSecret = $this->getBusinessValue($payment, 'PAYKEEPER_PASSWORD'); $orderId = $payment->getOrder()->getId(); $sum = $payment->getSum(); // Отримати токен $tokenResponse = $this->httpPost($apiUrl . '/info/settings/token/', [], [ 'Authorization: Basic ' . base64_encode("{$clientId}:{$clientSecret}"), ]); $token = $tokenResponse['token']; // Створити інвойс $invoiceParams = [ 'pay_amount' => number_format($sum, 2, '.', ''), 'clientid' => $payment->getOrder()->getUserId(), 'orderid' => $orderId, 'client_email' => $email, 'client_phone' => $phone, 'service_name' => 'Оплата замовлення №' . $orderId, ]; $invoiceParams['token'] = md5(implode('', $invoiceParams) . $token); $invoice = $this->httpPost($apiUrl . '/change/invoice/preview/', $invoiceParams); // $invoice['invoice_id'] — ID рахунку // Платіжна форма: $apiUrl . '/?id=' . $invoice['invoice_id'] 

Обробка сповіщень

PayKeeper надсилає POST на result_url при оплаті:

$clientSecret = $this->getBusinessValue($payment, 'PAYKEEPER_PASSWORD'); $id = $_POST['id']; $sum = $_POST['sum']; $orderId = $_POST['orderid']; $key = $_POST['key']; // Перевірка підпису $expected = md5($id . $sum . $orderId . $clientSecret); if (strtolower($key) !== strtolower($expected)) { http_response_code(400); echo 'bad signature'; exit; } // Додаткова перевірка через API $paymentInfo = $this->httpGet($apiUrl . '/info/payments/byid/', ['id' => $id], $token); if ($paymentInfo['status'] === 'paid') { // Підтвердити платіж у Бітрікс $order = \Bitrix\Sale\Order::loadByAccountNumber($orderId); // ... setPaid('Y'), save() } echo 'OK'; 

Чому обирають PayKeeper?

PayKeeper забезпечує значну економію на комісіях порівняно з іншими платіжними системами. Дані клієнтів залишаються на вашому сервері — ви не залежите від зовнішнього шлюзу. На відміну від Robokassa, тут повний контроль: свій домен, свої сертифікати. При цьому підтримуються всі функції: рахунки, повернення, фіскалізація.

Що таке self-hosted PayKeeper?

Оскільки PayKeeper можна встановити на вашому домені, URL API у кожного магазину свій. У налаштуваннях платіжної системи в Бітрікс потрібно передбачити поле для URL PayKeeper-сервера, а не хардкодити його. Це важливо при роботі з кількома магазинами або при зміні хостингу.

Повернення

PayKeeper підтримує повернення через API:

$refundParams = [ 'id' => $paykeeperPaymentId, 'amount' => number_format($refundAmount, 2, '.', ''), ]; $refundParams['token'] = md5(implode('', $refundParams) . $token); $result = $this->httpPost($apiUrl . '/change/payment/return/', $refundParams); 

Як забезпечити 54-ФЗ?

PayKeeper має вбудовану інтеграцію з онлайн-касами (ОФД). Дані чека передаються при створенні інвойсу в параметрах кошика. Склад позицій береться з $order->getBasket(). Налаштовуємо передачу всіх реквізитів для відповідності Федеральному закону 54-ФЗ. Гарантуємо коректну фіскалізацію повернень.

Обробка помилок та повторні спроби

PayKeeper може бути тимчасово недоступний або повернути помилку timeout. Тому в код інтеграції потрібно додати механізм черг:

// Якщо платіж не підтвердився, повторити через 5 хвилин if ($attempt < 3) { \Bitrix\Sale\PaymentCollection::addToQueue([ 'order_id' => $orderId, 'attempt' => $attempt + 1, 'next_try' => (new \DateTime())->modify('+5 minutes') ]); } 

Також важливо логувати всі запити та відповіді від PayKeeper для налагодження. Зберігайте в таблицю b_sale_payment_log або аналог всі POST-запити та responses з timestamp'ами.

Безпека при роботі з чутливими даними

Вимоги 54-ФЗ та ПДП:

• Не передавайте повні номери карток у логи — маскуйте останні 4 цифри
• Використовуйте HTTPS для всіх запитів (вимкніть перевірку сертифіката тільки в розробці)
• Зберігайте PAYKEEPER_PASSWORD тільки в .env або в захищеній таблиці конфігів, ніколи не в HTML

Типові помилки при інтеграції PayKeeper

• Не перевіряти підпис сповіщення. Без перевірки key зловмисник підробить сповіщення — ми завжди валідуємо md5 з секретом.
• Хардкодити URL сервера. PayKeeper може бути встановлений на будь-якому домені — використовуйте налаштування в адмінці, а не константи.
• Ігнорувати фіскалізацію часткових повернень. При частковому поверненні передавайте тільки повернуті позиції — це критично для ОФД.
• Пропускати чергу сповіщень. Якщо result_url завис, платіж залишається необробленим. Додайте фоновий job, який опитує статус щогодини.
• Плутати статуси платежів. PayKeeper поверне paid, failed, cancelled — обробляйте кожен статус правильно в Бітрікс.

Що входить у нашу роботу?

Терміни орієнтовно

Вартість розраховується індивідуально. Ми працюємо з будь-якими версіями Бітрікс (Cloud та On-Premise) і гарантуємо сумісність з останніми оновленнями. Зв'яжіться з нами для оцінки вашого проєкту та отримайте безкоштовну консультацію з інтеграції PayKeeper.