Интеграция платежного шлюза Webpay в мобильное приложение

Интеграция платежного шлюза Webpay в мобильное приложение

Webpay — белорусский платёжный шлюз, один из основных для приёма платежей на рынке Беларуси. Работает с белорусскими рублями, поддерживает карты Visa, Mastercard, Белкарт и ЕРИП. Нативного мобильного SDK нет — интеграция реализуется через WebView с платёжной формой или через серверный API с токенизацией.

Основной flow: WebView с платёжной формой

Наиболее распространённый подход. Сервер формирует POST-запрос к Webpay, получает URL платёжной формы, клиент открывает его в WebView.

Параметры запроса:

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).

// Android: открываем WebView
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()
                // Перехватываем deeplink возврата
                if (url.startsWith("yourapp://payment/")) {
                    handlePaymentReturn(url)
                    return true
                }
                return false
            }
        }

        // POST-форма через data URI
        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: WKWebView
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)
    }
}

Уведомление о результате: wsb_notify_url

Webpay отправляет POST-запрос на wsb_notify_url с результатом транзакции. Это основной механизм подтверждения — deeplink wsb_return_url ненадёжен (пользователь мог закрыть приложение).

Параметры уведомления включают 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)

Белкарт: особенности

Белкарт обрабатывается аналогично Visa/Mastercard, но Webpay поддерживает его только при наличии соответствующего договора с банком-эквайером. В тестовой среде Белкарт-карты доступны по тестовым реквизитам из документации Webpay.

Что входит в работу

• Серверная генерация параметров и подписи для Webpay
• Реализация WebView с перехватом deeplink-возврата
• Серверный обработчик wsb_notify_url с верификацией подписи
• Тестирование в тестовой среде Webpay
• Обработка ошибок и timeout сценариев

Сроки

2–3 дня. Стоимость рассчитывается индивидуально.