Webpay Payment System Integration
Webpay is Belarusian payment gateway, one of few directly operating in Belarus with support for Belkart cards, Visa, Mastercard and ERIP system. For Belarusian online stores and services Webpay remains one of main payment acceptance options.
Connection
Contract signed directly with Webpay (webpay.by). After contract signing:
-
store_id— store identifier -
secret_key— for signature
Test environment: https://test.webpay.by
Production environment: https://payment.webpay.by
Payment Initialization
Webpay works by POST-redirect scheme: HTML-form with parameters and signature formed, auto-submits on page load or button click.
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;
// Signature: MD5(seed + storeId + wsb_order_num + wsb_test + wsb_currency_id + wsb_total + secretKey)
$seed = time();
$wsb_test = env('WEBPAY_TEST', 1); // 1=test, 0=production
$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="Store">
<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">Go to Payment</button>
</form>
HTML;
}
Payment Notification (wsb_notify_url)
Webpay sends POST to wsb_notify_url after transaction:
public function notify(Request $request): Response
{
$data = $request->all();
// Check signature
$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);
}
// Check bank response code
if ((int)$data['wsb_result_code'] === 1) { // 1 = success
$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 — successful payment, 2 — rejection, 3 — customer cancellation.
Return Page
On wsb_return_url customer lands after payment. Order status already should be updated via notify. Just display result:
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,
]);
}
Don't rely on returnUrl parameters for success — only on status from DB, updated by notify-handler.
Order Items
Webpay supports order items transmission for details:
// Add to form for each item:
'wsb_invoice_item_name[0]' => 'Product 1',
'wsb_invoice_item_quantity[0]' => 1,
'wsb_invoice_item_price[0]' => '1500.00',
Testing
In test mode (wsb_test=1) test cards from Webpay docs used. Switch to production — wsb_test=0 and notify Webpay manager. Production activation takes 1–3 business days after testing several transactions.