Интеграция системы ЕРИП в мобильное приложение

Интеграция системы ЕРИП в мобильное приложение

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

Как работает ЕРИП в мобильном контексте

Ваше приложение создаёт счёт в ЕРИП через 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: CoreImage QR генерация
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-экраном. Стоимость рассчитывается индивидуально после анализа требований и выбора агрегатора.