Webpay Integration: Accept Payments on Your Site
When integrating the Webpay payment gateway, developers often make the same mistake — incorrect concatenation order when forming the signature. As a result, payments fail with an authentication error, and clients lose trust. We'll break down how to set up acceptance of Visa, Mastercard, and Belkart cards without hidden issues, and show a proven algorithm. The time savings on debugging can reach 40%.
Webpay remains a key payment gateway for Belarusian projects thanks to its support for ERIP and Belkart. Without it, you lose up to 30% of the audience that does not use international cards. Unlike Stripe or PayPal, Webpay provides local processing and reduces commission by 15–20%. In a real case for an online store with a turnover of 10,000 BYN, the commission savings amounted to 250 BYN per month. We have integrated Webpay for 20+ projects and have accumulated experience that allows us to avoid typical pitfalls.
Webpay processes payments via ERIP 3 times faster than other providers' APIs — this is critical for mass mailings and promotions.
What problems do we solve during integration?
Signature errors are the most common pain point. The parameters are concatenated in a strict order: seed, store_id, order_num, test_flag, currency, amount, secret_key. If you change the order, the signature won't match. Use our template.
Incorrect processing of notifications — the notify handler must check not only the signature but also the result code (wsb_result_code). Success is only code 1. Everything else is a decline or cancellation.
Session loss on redirect — Webpay uses POST redirect. Create a form with auto-submit via JavaScript to avoid clicks and errors. According to Webpay documentation, all fields are mandatory.
How to avoid signature errors when integrating Webpay?
Here is an example of payment initialization in 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;
}
Why should the notify handler return HTTP 200?
When receiving a POST to wsb_notify_url, check the signature and the result code:
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 — success, 2 — decline, 3 — buyer cancellation.
What to do on the return page?
Do not rely on parameters in the returnUrl — use the order status from the database, which is updated by the notify handler:
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]);
}
How to handle refunds via Webpay?
Refunds are performed through the Webpay admin panel or API. Ensure the refund amount does not exceed the original. For debugging, use the test environment: check that the test certificate has not expired. For API refunds, the signature is formed using the same algorithm but with the operation parameters.
What to do in case of a connection timeout?
If the request to Webpay does not respond for more than 30 seconds, initiate a new request with the same order_num. Idempotency is guaranteed by the uniqueness of order_num — re-sending with the same number will not create a duplicate. Set a timeout on the client side and log all timeouts for analysis.
Comparison of test and live environments
| Parameter | Test environment | Live environment |
|---|---|---|
| URL | test.webpay.by | payment.webpay.by |
| wsb_test | 1 | 0 |
| Cards | Test cards from documentation | Real cards |
| Activation | Instant | 1–3 business days after testing |
Error codes table and their handling
| Result code | Description | Action |
|---|---|---|
| 1 | Successful payment | Update order status to 'paid' |
| 2 | Bank decline | Notify the client and suggest another card |
| 3 | Buyer cancellation | Return to cart page |
| Other | Technical error | Log and return HTTP 400 |
When testing refunds, cross-check amounts and use the same keys. All scenarios must be run through before switching to live mode.
Work process: from analysis to deployment
- Analysis — we study your store, choose the integration method (ready-made modules or custom).
- Design — we agree on the payment flow scheme, notification URLs.
- Implementation — we implement the payment form, handlers, refunds.
- Testing — we run all scenarios in the test environment: success, decline, timeout.
- Deployment — we activate live mode, monitor the first transactions.
What is included in the work?
- Integration documentation (scheme, method descriptions).
- Testing of 10+ payment scenarios.
- Training your administrator on handling refunds and Webpay reports.
- Support for 30 days after launch.
Timeline and cost
Webpay integration takes from 5 to 10 business days depending on the complexity of the store. The cost is calculated individually. We will estimate your project for free after reviewing your site — get in touch. Order integration and get a consultation from an engineer.
Why trust us with the integration?
Over 10 years of experience in web development, 50+ successfully launched integrations with payment systems. We guarantee correct processing of all transaction types and the absence of signature errors. Our solutions undergo security audits. Get a consultation — we will evaluate your project within 1 day.