Інтеграція платіїної системи Webpay на сайт
Webpay — білоруський платіжний шлюз, один з небагатьох, що працюють безпосередньо у Беларуси з підтримкою карт Белкарт, Visa, Mastercard та системи ЕРИП. Для білоруських інтернет-магазинів та сервісів Webpay залишається одним з основних варіантів приймання платежів.
Підключення
Договір укладається прямо з Webpay (webpay.by). Після укладення договору видаються:
-
store_id— ідентифікатор магазину -
secret_key— для підпису
Тестове середовище: https://test.webpay.by
Боевое середовище: https://payment.webpay.by
Ініціалізація платежу
Webpay працює по схемі POST-редиректа: формується HTML-форма з параметрами та підписом, яка автосабмититься при завантаженні сторінки або при клику на кнопку.
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;
// Підпис: MD5(seed + storeId + wsb_order_num + wsb_test + wsb_currency_id + wsb_total + secretKey)
$seed = time();
$wsb_test = env('WEBPAY_TEST', 1); // 1=тест, 0=боевой
$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;
}
Сповіщення про оплату (wsb_notify_url)
Webpay відправляє 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) { // 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 — скасування покупцем.
Сторінка повернення
На wsb_return_url покупець потрапляє після оплати. Статус замовлення уже повинен бути оновлений через 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,
]);
}
Не полягатися на параметрах у returnUrl для визначення успіху — тільки на статусі з БД, оновленому notify-обробником.
Позиції замовлення
Webpay підтримує передачу позицій для деталізації:
// Додати у форму для кожної позиції:
'wsb_invoice_item_name[0]' => 'Товар 1',
'wsb_invoice_item_quantity[0]' => 1,
'wsb_invoice_item_price[0]' => '1500.00',
Тестування
У тестовому режимі (wsb_test=1) для оплати використовуються карти з документації Webpay. Переключення у боевой режим — wsb_test=0 та сповіщення менеджера Webpay. Активація боевого режиму займає від 1 до 3 робочих днів після тестування кількох транзакцій.