Інтеграція платіжного шлюзу Webpay в мобільний додаток

Інтеграція платіжного шлюзу Webpay в мобільному додатку

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

Основний потік: 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 дні. Вартість розраховується індивідуально.