Інтеграція системи ЄРІП в мобільний додаток

Інтеграція системи ЕРИП в мобільному додатку

ЕРИП (Єдиний розрахунково-інформаційний простір) — білоруська міжбанківська система оплати. Відрізняється від більшості платіжних шлюзів: ЕРИП не обробляє карточні реквізити, а створює рахунок у системі, який користувач оплачує через будь-який білоруський банк — інтернет-банк, мобільний банкінг, термінал або касу. Для мобільного додатку це означає, що сам платіж відбувається поза вашим додатком.

Як ЕРИП працює в мобільному контексті

Ваш додаток створює рахунок в ЕРИП через API, отримує номер рахунку (QR-код або числовой код), користувач оплачує через своє банківське приложение. Система повідомляє ваш сервер про факт оплати через callback.

Два варіанти технічного підключення:

1. Пряме підключення до ЕРИП — через НКФО «ЕРИПС» напрямо, вимагає договору та сертифіката
2. Через агрегатора — Webpay, iPay, bePaid приймають оплату через ЕРИП і надають простіший API

Інтеграція через агрегатор bePaid

bePaid — білоруський платіжний шлюз з підтримкою ЕРИП API. Найзручніший варіант для мобільних додатків.

Серверна частина: створення транзакції з ЕРИП

POST https://checkout.bepaid.by/transactions/payment_token
Authorization: Basic base64(shop_id:secret_key)
Content-Type: application/json

{
    "checkout": {
        "transaction_type": "payment",
        "order": {
            "amount": 1500,
            "currency": "BYN",
            "description": "Замовлення №1234",
            "tracking_id": "ORDER-1234"
        },
        "settings": {
            "success_url": "yourapp://payment/success",
            "decline_url": "yourapp://payment/decline",
            "fail_url": "yourapp://payment/fail",
            "notification_url": "https://your-server.com/bepaid/notify"
        },
        "payment_method": {
            "types": ["erip"],
            "erip": {
                "service_no": 12345678,  // ваш номер послуги в ЕРИП
                "account_number": "ORDER-1234",
                "service_info": ["Оплата замовлення №1234"]
            }
        }
    }
}

Відповідь містить checkout_url — посилання на сторінку bePaid з QR-кодом ЕРИП.

Мобільний клієнт: відображення QR-коду

Два варіанти:

1. WebView зі сторінкою bePaid — відкриваємо checkout_url в WebView або SFSafariViewController / Chrome Custom Tabs. Сторінка bePaid показує QR-код та інструкції.

2. Нативний екран з QR — сервер отримує дані ЕРИП-рахунку, додаток генерує QR самостійно.

// Android: генерація QR через ZXing
implementation("com.google.zxing:core:3.5.2")
implementation("com.journeyapps:zxing-android-embedded:4.3.0")

val qrData = "SYSTEM_ERIP|${serviceNo}|${accountNumber}|${amount}"

val qrBitmap = QRCodeWriter().encode(
    qrData,
    BarcodeFormat.QR_CODE,
    512,
    512
).let { bitMatrix ->
    val width = bitMatrix.width
    val height = bitMatrix.height
    Bitmap.createBitmap(width, height, Bitmap.Config.RGB_565).apply {
        for (x in 0 until width) {
            for (y in 0 until height) {
                setPixel(x, y, if (bitMatrix[x, y]) Color.BLACK else Color.WHITE)
            }
        }
    }
}

imageView.setImageBitmap(qrBitmap)

// iOS: генерація QR за допомогою CoreImage
import CoreImage

func generateQRCode(from string: String) -> UIImage? {
    let filter = CIFilter.qrCodeGenerator()
    filter.message = Data(string.utf8)
    filter.correctionLevel = "M"

    guard let outputImage = filter.outputImage else { return nil }
    let scale = UIScreen.main.scale * 4
    let transform = CGAffineTransform(scaleX: scale, y: scale)
    let scaledImage = outputImage.transformed(by: transform)

    return UIImage(ciImage: scaledImage)
}

let qrData = "SYSTEM_ERIP|\(serviceNo)|\(accountNumber)|\(amount)"
qrImageView.image = generateQRCode(from: qrData)

Polling статусу та Push-сповіщення

ЕРИП — асинхронна система. Користувач може оплатити через 5 хвилин або через 2 години. Два підходи до відслідковування:

Webhook (рекомендується). bePaid / Webpay відправляє POST на notification_url при оплаті. Сервер отримує сповіщення, оновлює замовлення, відправляє Push користувачу через FCM/APNs.

Polling. Клієнт періодично запитує статус у вашого сервера. Навантажує сервер, але простіше реалізується:

// Android: polling через корутини
private fun startPaymentPolling(orderId: String) {
    lifecycleScope.launch {
        repeat(60) {  // максимум 60 спроб
            delay(5000L)  // кожні 5 секунд
            val status = paymentRepository.checkStatus(orderId)
            if (status == PaymentStatus.PAID) {
                handleSuccess()
                return@launch
            }
        }
        // Після 5 хвилин — пропонуємо перевірити вручну
    }
}

Пряме підключення до ЕРИП (для крупних мерчантів)

При прямому підключенні використовується SOAP API ЕРИПС. Вимагає:

• Заключення договору з НКФО «ЕРИПС»
• Отримання сертифіката
• Налаштування XML-підпису запитів

Технічно складніше, але дає більше контролю: можна створювати рахунки з довільними реквізитами, отримувати детальний аналіз транзакцій.

Типові проблеми

Користувач оплатив, але рахунок не закрився. Webhook не дійшов через помилку мережі. Потрібно реалізувати повторні спроби отримання webhook або періодичну reconciliation — сверку статусів через API агрегатора.

QR не сканується банківським приложением. Формат ЕРИП-QR строго стандартизований. Використовуйте специфікацію НКФО «ЕРИПС» для формування рядка — довільний формат не сработає.

Обсяг робіт

• Підключення до ЕРИП через агрегатор (bePaid, Webpay) або пряме
• Серверний endpoint для створення ЕРИП-рахунку
• Нативний екран з QR-кодом або WebView зі сторінкою checkout
• Webhook обработчик для отримання статусу оплати
• Push-сповіщення користувачу після успішної оплати

Терміни

3–5 днів для інтеграції через агрегатор з нативним QR-екраном. Вартість розраховується індивідуально після аналізу вимог та вибору агрегатора.