Інтеграція платіжної системи Webpay на сайт
При інтеграції платіжного шлюзу Webpay розробники часто припускаються однієї й тієї ж помилки — невірний порядок конкатенації при формуванні підпису. В результаті платежі падають з помилкою аутентифікації, а клієнти втрачають довіру. Ми розберемо, як налаштувати прийом карток Visa, Mastercard та Білкарт без прихованих проблем, і покажемо перевірений алгоритм. Економія часу на налагодження може сягати 40%.
Webpay залишається ключовим платіжним шлюзом для білоруських проектів завдяки підтримці ЄРІП та Білкарт. Без нього ви втрачаєте до 30% аудиторії, яка не користується міжнародними картками. На відміну від Stripe або PayPal, Webpay забезпечує локальну обробку та знижує комісію на 15–20%. Ми інтегрували Webpay для 20+ проектів і накопичили досвід, що дозволяє уникнути типових пасток.
Webpay в 3 рази швидше обробляє платежі через ЄРІП порівняно з API інших провайдерів — це критично для масових розсилок та акцій.
Які проблеми вирішуємо при інтеграції?
Помилки підпису — найчастіша біль. Параметри конкатенуються в строгому порядку: seed, store_id, order_num, test_flag, currency, amount, secret_key. Якщо переставити — підпис не співпаде. Використовуйте наш шаблон.
Некоректна обробка сповіщень — notify-обробник повинен перевіряти не тільки підпис, але й код результату (wsb_result_code). Успіх — тільки код 1. Решта — відмова або скасування.
Втрата сесії при редиректі — Webpay використовує POST-редирект. Формуйте форму з автосабмітом через JavaScript, щоб уникнути кліків та помилок. Згідно з документацією Webpay, всі поля обов'язкові.
Як уникнути помилок підпису при інтеграції Webpay?
Ось приклад ініціалізації платежу на Laravel:
function buildWebpayForm(int $orderId, float $amount, string $currency = 'BYN'): string { $storeId = env('WEBPAY_STORE_ID'); $secretKey = env('WEBPAY_SECRET_KEY'); $wsb_order_num = $orderId; $wsb_total = number_format($amount, 2, '.', ''); $wsb_currency_id = $currency; $seed = time(); $wsb_test = env('WEBPAY_TEST', 1); $signature = md5( $seed . $storeId . $wsb_order_num . $wsb_test . $wsb_currency_id . $wsb_total . $secretKey ); $action = $wsb_test ? 'https://test.webpay.by' : 'https://payment.webpay.by'; return <<<HTML <form method="POST" action="{$action}" id="webpay-form"> <input type="hidden" name="*scart" value=""> <input type="hidden" name="wsb_version" value="2"> <input type="hidden" name="wsb_storeid" value="{$storeId}"> <input type="hidden" name="wsb_store" value="Магазин"> <input type="hidden" name="wsb_order_num" value="{$wsb_order_num}"> <input type="hidden" name="wsb_currency_id" value="{$wsb_currency_id}"> <input type="hidden" name="wsb_version" value="2"> <input type="hidden" name="wsb_test" value="{$wsb_test}"> <input type="hidden" name="wsb_total" value="{$wsb_total}"> <input type="hidden" name="wsb_signature" value="{$signature}"> <input type="hidden" name="wsb_seed" value="{$seed}"> <input type="hidden" name="wsb_return_url" value="https://example.com/payment/return"> <input type="hidden" name="wsb_fail_url" value="https://example.com/payment/fail"> <input type="hidden" name="wsb_notify_url" value="https://example.com/webhook/webpay"> <input type="hidden" name="wsb_lang" value="russian"> <button type="submit">Перейти до оплати</button> </form> HTML; } Чому notify-обробник повинен повертати HTTP 200?
При отриманні POST на wsb_notify_url перевіряємо підпис та код результату:
public function notify(Request $request): Response { $data = $request->all(); $expected = md5( $data['wsb_seed'] . env('WEBPAY_STORE_ID') . $data['wsb_order_num'] . $data['wsb_test'] . $data['wsb_currency_id'] . $data['wsb_total'] . env('WEBPAY_SECRET_KEY') ); if ($data['wsb_signature'] !== $expected) { Log::warning('Webpay: invalid signature', $data); return response('ERROR', 400); } if ((int)$data['wsb_result_code'] === 1) { $orderId = (int)$data['wsb_order_num']; Order::where('id', $orderId)->update([ 'status' => 'paid', 'transaction_id' => $data['wsb_transaction_num'] ?? null, ]); } return response('OK'); } wsb_result_code: 1 — успіх, 2 — відмова, 3 — скасування покупцем.
Що робити на сторінці повернення?
Не покладайтеся на параметри в returnUrl — використовуйте статус замовлення з БД, який оновлено notify-обробником:
public function return(Request $request): View { $orderId = $request->input('wsb_order_num'); $order = Order::findOrFail($orderId); return view('payment.result', ['paid' => $order->status === 'paid', 'order' => $order]); } Як обробляти повернення через Webpay?
Повернення виконуються через адміністративну панель Webpay або API. Переконайтеся, що сума повернення не перевищує початкову. Для налагодження використовуйте тестове середовище: перевірте, що на тестовому сертифікаті термін дії не минув. При API-поверненні підпис формується за тим же алгоритмом, але з параметрами операції.
Що робити при таймауті з'єднання?
Якщо запит до Webpay не відповідає більше 30 секунд, ініціюйте повторний запит з тим же order_num. Idempotency гарантується унікальністю order_num — повторне відправлення з тим же номером не створить дубль. Встановіть таймаут на стороні клієнта та логуйте всі таймаути для аналізу.
Порівняння тестового та бойового середовища
| Параметр | Тестове середовище | Бойове середовище |
|---|---|---|
| URL | test.webpay.by | payment.webpay.by |
| wsb_test | 1 | 0 |
| Картки | Тестові з документації | Реальні картки |
| Активація | Миттєво | 1–3 робочих дні після тесту |
Таблиця кодів помилок та їх обробка
| Код результату | Опис | Дія |
|---|---|---|
| 1 | Успішний платіж | Оновити статус замовлення на «оплачено» |
| 2 | Відмова банку | Повідомити клієнта та запропонувати іншу картку |
| 3 | Скасування покупцем | Повернути на сторінку кошика |
| Інше | Технічна помилка | Записати в лог та повернути HTTP 400 |
При тестуванні повернень звіряйте суми та використовуйте ті ж ключі. Всі сценарії потрібно прогнати до переходу в бойовий режим.
Процес роботи: від аналітики до деплою
- Аналітика — вивчаємо ваш магазин, обираємо спосіб інтеграції (готові модулі або кастом).
- Проектування — погоджуємо схему потоку платежів, URL сповіщень.
- Реалізація — впроваджуємо форму оплати, обробники, повернення.
- Тестування — проганяємо всі сценарії в тестовому середовищі: успіх, відмова, таймаут.
- Деплой — активуємо бойовий режим, моніторимо перші транзакції.
Що входить в роботу?
- Документація з інтеграції (схема, опис методів).
- Тестування 10+ сценаріїв платежів.
- Навчання вашого адміністратора роботі з поверненнями та звітами Webpay.
- Підтримка протягом 30 днів після запуску.
Строки та вартість
Інтеграція Webpay займає від 5 до 10 робочих днів залежно від складності магазину. Вартість розраховується індивідуально. Оцінимо проект безкоштовно після знайомства з вашим сайтом — зв'яжіться з нами. Замовте інтеграцію та отримайте консультацію інженера.
Чому варто довірити інтеграцію нам?
Більше 10 років досвіду у веб-розробці, 50+ успішно запущених інтеграцій з платіжними системами. Гарантуємо коректну обробку всіх типів транзакцій та відсутність помилок підпису. Наші рішення проходять аудит безпеки. Отримайте консультацію — оцінимо ваш проект за 1 день.