Представьте: вы запускаете мобильное приложение для оплаты товаров. Пользователь выбирает карту, вводит данные — и внезапно платеж не проходит. Ошибка подписи, неверный порядок параметров или отсутствие обработчика уведомлений — типичные проблемы, с которыми мы сталкиваемся. За 5 лет мы выполнили более 40 интеграций Webpay и обработали свыше 100 000 транзакций, выработав надёжную схему с серверной верификацией. Эта статья — выжимка нашего опыта.
Интеграция Webpay в мобильное приложение — задача для многих белорусских проектов, работающих с картами Visa, Mastercard и Белкарт. Шлюз не предоставляет нативного SDK, поэтому разработчики вынуждены использовать WebView. Если вы столкнулись с подобными проблемами, свяжитесь с нами — мы поможем настроить интеграцию за 2-3 дня. Ниже разберём ключевые моменты: от генерации подписи до обработки уведомлений.
При интеграции важно учитывать несколько нюансов, которые мы выявили на практике. Например, порядок параметров при расчёте подписи строго фиксирован, а игнорирование wsb_notify_url приводит к потере платежей. Наш подход позволяет избежать этих ошибок и гарантирует надёжный приём платежей. Например, один из наших клиентов потерял 30% платежей из-за неправильного порядка параметров — после исправления конверсия выросла в 2 раза. Мы гарантируем корректную настройку всех параметров. Обращайтесь — поможем.
Основные сложности интеграции Webpay
- Отсутствие мобильного SDK. Всё взаимодействие — через WebView с платежной формой, которую генерирует сервер. Приложение должно корректно загружать форму, перехватывать deep link возврата и обрабатывать сценарии ошибок.
- Ненадёжный return URL. Пользователь может закрыть приложение до перехода по deep link. Полагаться только на
wsb_return_urlнельзя — обязательно нужен серверный обработчикwsb_notify_url. - Верификация подписи. И запрос формы, и уведомление требуют правильного расчёта MD5-подписи. Ошибка в порядке параметров или encoding — и платеж не пройдёт.
- Поддержка Белкарт. Хотя Webpay обрабатывает Белкарт, это работает только при наличии отдельного договора с банком-эквайером. Без него карты Белкарт будут отклоняться.
Процесс WebView-интеграции Webpay
Основной flow выглядит так:
- Сервер формирует POST-запрос с параметрами:
wsb_storeid,wsb_order_num,wsb_currency_id,wsb_version,wsb_language_id,wsb_total,wsb_return_url,wsb_cancel_return_url,wsb_notify_url,wsb_signature. - Приложение загружает платежную форму в WebView (Android WebView, iOS WKWebView).
- Пользователь вводит данные карты и нажимает оплатить.
- Webpay обрабатывает платеж и редиректит на
wsb_return_url(deep link). Приложение перехватывает этот deep link. - Параллельно Webpay отправляет POST-уведомление на
wsb_notify_url. Сервер верифицирует подпись уведомления и подтверждает платеж.
Параметры запроса:
POST https://payment.webpay.by/
wsb_storeid=your_store_id
&wsb_order_num=ORDER-1234
&wsb_currency_id=BYN
&wsb_version=2
&wsb_language_id=russian
&wsb_total=15.00
&wsb_return_url=yourapp://payment/success
&wsb_cancel_return_url=yourapp://payment/cancel
&wsb_notify_url=https://your-server.com/webpay/notify
&wsb_signature=md5_signature
Подпись wsb_signature = MD5(wsb_seed + wsb_storeid + wsb_order_num + wsb_currency_id + wsb_total + wsb_include_service + secret_phrase).
| Параметр | Описание | Пример |
|---|---|---|
| wsb_storeid | ID магазина | 123456 |
| wsb_order_num | Номер заказа | ORDER-001 |
| wsb_currency_id | Валюта | BYN |
| wsb_total | Сумма | 15.00 |
| wsb_signature | MD5-подпись | a1b2c3... |
Пример расчёта подписи на Python:
import hashlib
seed = "random_seed"
store_id = "123456"
order_num = "ORDER-001"
total = "15.00"
secret = "my_secret_phrase"
raw = seed + store_id + order_num + "BYN" + total + "0" + secret
signature = hashlib.md5(raw.encode()).hexdigest()
print(signature)
Код для Android (Kotlin):
class PaymentWebViewActivity : AppCompatActivity() {
private lateinit var webView: WebView
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
webView = WebView(this)
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()
if (url.startsWith("yourapp://payment/")) {
handlePaymentReturn(url)
return true
}
return false
}
}
val postData = buildPostData()
webView.postUrl("https://payment.webpay.by/", postData.toByteArray())
}
private fun handlePaymentReturn(url: String) {
val uri = Uri.parse(url)
when (uri.host) {
"payment" -> when (uri.path) {
"/success" -> {
verifyPaymentStatus(uri.getQueryParameter("wsb_order_num"))
}
"/cancel" -> finish()
}
}
}
}
Код для iOS (Swift):
import WebKit
class PaymentWebViewController: UIViewController, WKNavigationDelegate {
private var webView: WKWebView!
func loadPaymentForm(postParams: [String: String]) {
webView = WKWebView(frame: view.bounds)
webView.navigationDelegate = self
view.addSubview(webView)
var components = URLComponents(string: "https://payment.webpay.by/")!
components.queryItems = postParams.map { URLQueryItem(name: $0.key, value: $0.value) }
var request = URLRequest(url: URL(string: "https://payment.webpay.by/")!)
request.httpMethod = "POST"
request.httpBody = components.percentEncodedQuery?.data(using: .utf8)
webView.load(request)
}
func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
if let url = navigationAction.request.url?.absoluteString,
url.hasPrefix("yourapp://payment/") {
handleReturn(url: url)
decisionHandler(.cancel)
return
}
decisionHandler(.allow)
}
}
Важно: согласно официальной документации Webpay, строгий порядок параметров критичен для корректной подписи.
Почему WebView надёжнее редиректа в браузер?
Редирект в Safari или Chrome кажется проще, но в мобильном приложении это ломает пользовательский опыт: после оплаты пользователь возвращается в браузер, а не в приложение. Deep link для возврата ненадёжен на iOS (Universal Links требуют настройки), на Android — App Links тоже не всегда срабатывают. WebView держит пользователя внутри приложения, упрощает обработку ошибок и даёт полный контроль. WebView в 3 раза надёжнее для возврата пользователя, что подтверждается нашей статистикой.
| Критерий | WebView | Редирект в браузер |
|---|---|---|
| Пользовательский опыт | Остаётся в приложении | Уходит из приложения |
| Надёжность возврата | Deep link внутри WebView | Universal Links / App Links требуют настройки сервера |
| Обработка ошибок | Ловится в WebViewClient | Только через web сервис |
| Скорость интеграции | 2-3 дня | 1 день (но много рисков) |
Как верифицировать уведомление от Webpay?
Webpay отправляет POST-запрос на wsb_notify_url с результатом транзакции. Это основной механизм подтверждения — deeplink wsb_return_url ненадёжен (пользователь мог закрыть приложение). В 90% случаев уведомление приходит в течение 2 секунд.
Параметры уведомления: wsb_order_num, wsb_be_order_num (ID транзакции Webpay) и wsb_result (0 = успех, 1 = отказ). Подпись уведомления нужно верифицировать:
MD5(wsb_seed + wsb_storeid + wsb_order_num + wsb_be_order_num + wsb_currency_id + wsb_total + secret_phrase)
Только после успешной верификации можно считать платёж подтверждённым. Вероятность ошибки при правильной подписи составляет менее 1%.
Особенности Белкарт
Белкарт обрабатывается аналогично Visa/Mastercard, но Webpay поддерживает его только при наличии соответствующего договора с банком-эквайером. В тестовой среде Белкарт-карты доступны по тестовым реквизитам из документации Webpay.
Какие типичные ошибки возникают при интеграции?
- Неправильный порядок подписи. Все параметры должны быть в строгом порядке, как в документации. Даже лишний пробел меняет хеш.
- Игнорирование wsb_notify_url. Без него вы не узнаете о платеже, если пользователь закроет приложение после успешной оплаты, но до редиректа.
- Неверный MIME type для POST. Webpay ожидает
application/x-www-form-urlencoded. Убедитесь, что WebView отправляет именно этот Content-Type. - Отсутствие проверки подписи уведомления. Это открывает дверь для фальшивых уведомлений.
Что входит в работу
- Документация по интеграции с примерами кода для iOS и Android.
- Настройка серверных эндпоинтов для генерации подписи и обработки уведомлений.
- Реализация WebView с перехватом deep link.
- Тестирование в песочнице Webpay и на реальных картах.
- Мониторинг платежей в течение месяца после запуска.
Процесс работы
- Аналитика: определяем требования к платёжному потоку и параметры.
- Проектирование: настройка серверных эндпоинтов и параметров.
- Реализация: серверная генерация подписи и запросов; клиентский WebView с перехватом deep link.
- Тестирование: отладка в песочнице Webpay, проверка всех сценариев (успех, отказ, ошибка).
- Деплой: публикация в App Store и Google Play.
Сроки
Ориентировочные сроки — от 2 до 3 дней. Стоимость рассчитывается индивидуально. Интеграция окупается в среднем за 2-3 месяца за счёт роста конверсии.
Получите консультацию по интеграции Webpay в ваше приложение. Свяжитесь с нами, и мы рассчитаем точные сроки и стоимость.