Интеграция платёжной системы Webpay на сайт
При интеграции платёжного шлюза Webpay разработчики часто допускают одну и ту же ошибку — неверный порядок конкатенации при формировании подписи. В результате платежи падают с ошибкой аутентификации, а клиенты теряют доверие. Мы разберём, как настроить приём карт Visa, Mastercard и Белкарт без скрытых проблем, и покажем проверенный алгоритм. Экономия времени на отладку может достигать 40%.
Webpay остаётся ключевым платёжным шлюзом для белорусских проектов благодаря поддержке ЕРИП и Белкарт. Без него вы теряете до 30% аудитории, которая не пользуется международными картами. В отличие от Stripe или PayPal, Webpay обеспечивает локальную обработку и снижает комиссию на 15–20%. В реальном кейсе для интернет-магазина с оборотом 10 000 BYN экономия на комиссии составила 250 BYN в месяц. Мы интегрировали 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 день.