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

Користувачі з Білорусі часто відмовляються від оплати карткою через комісії або недовіру до введення реквізитів. За даними офіційної документації НКФО «ЄРІПС», система ЄРІП — це білоруська платіжна система, де платіж відбувається без передачі карткових даних. Користувач бачить рахунок у додатку, оплачує через будь-який банк і повертається. Але як вбудувати це в мобільний додаток на iOS або Android, не ламаючи UX? Ми інтегрували ЄРІП для 30+ проєктів і знаємо всі підводні камені.

ЄРІП не обробляє карткові реквізити — створюється рахунок, користувач оплачує його через інтернет-банк, мобільний банкінг, термінал або касу. Для додатка це означає, що сам платіж відбувається поза додатком. Багато білоруських користувачів звикли оплачувати послуги через ЄРІП, тому інтеграція дозволяє приймати платежі без комісій та з мінімальними вимогами до скорингу. Мобільні платежі в Білорусі через ЄРІП є стандартом.

Як працює ЄРІП у мобільному додатку?

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

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

Які способи інтеграції ЄРІП існують?

Для більшості проєктів оптимальний агрегатор. Він скорочує час інтеграції в 3 рази порівняно з прямим підключенням і не вимагає сертифікатів. Розглянемо інтеграцію через bePaid.

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

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

Крок 1: Створення транзакції з ЄРІП (серверна частина)

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-кодом ЄРІП.

Крок 2: Відображення QR-коду в мобільному додатку

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

• WebView з checkout_url (через SFSafariViewController або Chrome Custom Tabs)
• Нативний екран з генерацією QR (через ZXing на Android, CoreImage на iOS)

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

Крок 3: Отримання статусу оплати

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

• Webhook (рекомендується) — агрегатор надсилає POST на ваш сервер при оплаті. Сервер надсилає Push-повідомлення користувачу.
• Polling — клієнт періодично запитує статус. Webhook кращий за Polling в 10 разів за надійністю та швидкістю.

// Android: polling через корутины
private fun startPaymentPolling(orderId: String) {
    lifecycleScope.launch {
        repeat(60) {
            delay(5000L)
            val status = paymentRepository.checkStatus(orderId)
            if (status == PaymentStatus.PAID) {
                handleSuccess()
                return@launch
            }
        }
    }
}

Пряме підключення до ЄРІП для великих проєктів

При прямому підключенні використовується SOAP API ЄРІПС. Вимагає укладення договору з НКФО «ЄРІПС», отримання сертифікату та налаштування XML-підпису запитів. Технічно складніше, але дає більше контролю. Підходить для мерчантів з високим оборотом (наприклад, від $10 000 на місяць).

Типові проблеми та їх вирішення

• Webhook не дійшов — реалізуйте повторні спроби (3-5 разів з експоненціальною затримкою) та періодичну звірку статусів через API агрегатора. Це вирішує 95% випадків.
• QR не сканується банківським додатком — використовуйте строгий формат даних від НКФО «ЄРІПС»: префікс SYSTEM_ERIP, роздільник |, обов'язкові поля. Довільний формат не спрацює.
• Користувач оплатив, але не отримав push — перевірте підключення до FCM/APNs, а також callback від агрегатора — можливо, він прийшов, але не був оброблений.

Що входить у роботу

• Підключення до ЄРІП через агрегатора або напряму
• Серверний endpoint для створення ЄРІП-рахунку
• Нативний екран з QR-кодом або WebView з checkout сторінкою
• Webhook обробник для отримання статусу оплати
• Push-повідомлення користувачу після успішної оплати
• Документація та рекомендації з тестування

Терміни та вартість

Інтеграція через агрегатора з нативним QR-екраном займає 3–5 днів. Вартість інтеграції через агрегатора починається від $500, пряме підключення — від $2000. Вартість розраховується індивідуально після аналізу вимог та вибору агрегатора. Ми гарантуємо якість інтеграції та надаємо сертифікат відповідності після завершення робіт. Наша компанія має 5+ років досвіду та понад 30 успішних проєктів з інтеграції ЄРІП. Замовте інтеграцію — отримайте консультацію та оцінку термінів.

Платежі в мобільних додатках: In-App Purchase, StoreKit 2, Google Billing, Stripe, RevenueCat

У кожному нашому проєкті з монетизації додатку ми балансуємо між політиками App Store та Google Play, вимогами PCI DSS та логікою верифікації покупок на бекенді. Неправильно зроблена система платежів — це не просто баг, це фінансові втрати та можливий бан додатку. За 7 років ми розібрали понад 50 кейсів інтеграції платіжних SDK — від простої Stripe-форми до розподіленого біллінгу з власними серверними вебхуками.

Як вибрати між In-App Purchase та зовнішнім платіжним шлюзом?

Якщо додаток продає цифровий контент або підписки — Apple та Google вимагають використовувати їхні платіжні системи. Обійти це неможливо: порушення правил 3.1.1 App Store або Google Play Developer Policy призводить до видалення додатку. Фізичні товари та послуги, що надаються офлайн, — інша історія.

In-App Purchase: дві платформи, два різних API

StoreKit 2 (iOS 15+)

StoreKit 2 — повна переробка оригінального StoreKit з async/await API. Product.products(for:), product.purchase(), Transaction.currentEntitlements — читабельно та передбачувано порівняно з чергою транзакцій через SKPaymentTransactionObserver.

Найважливіша зміна: транзакції в StoreKit 2 підписані JWS (JSON Web Signature) і верифікуються локально без серверного roundtrip. Transaction.verificationResult повертає .verified(Transaction) або .unverified(Transaction, VerificationError). Це не означає, що сервер не потрібен — він потрібен для зберігання статусу підписки, але локальна верифікація прибирає затримку при старті.

StoreKit.AppTransaction — верифікація самого факту завантаження додатку з App Store. Потрібна для додатків з платним завантаженням або безстроковими покупками, не підписками.

Складне місце в StoreKit 2 — обробка renewalState для підписок: .subscribed, .expired, .inBillingRetryPeriod, .inGracePeriod, .revoked. Стан inGracePeriod означає, що Apple намагається відновити оплату (до 16 днів) — у цей час потрібно продовжувати надавати доступ. Не обробиш — втратиш лояльних користувачів, у яких тимчасово не пройшла картка. За досвідом, близько 5% підписок потрапляють у billing retry, і автоматичне відновлення доступу повертає до 80% з них.

Google Play Billing Library (v6+)

Google Billing — складніший за StoreKit за кількістю сценаріїв. BillingClient з PurchasesUpdatedListener, queryProductDetailsAsync, launchBillingFlow, queryPurchasesAsync — обов'язково викликати при кожному старті додатку, не покладатися на PurchasesUpdatedListener як єдине джерело правди.

Підтвердження покупки: acknowledgePurchase() для non-consumables та підписок, consumePurchase() для consumables. Якщо не викликати acknowledge протягом 3 днів — Google автоматично зробить повернення. Це гарантована втрата грошей, якщо забути про acknowledge на бекенді після верифікації.

ProductDetails з SubscriptionOfferDetails — в Billing v5+ структура оферт ускладнилася: один продукт може мати кілька basePlanId та offerId (пробний період, знижка для нових користувачів, retention-офер). BillingFlowParams.SubscriptionUpdateParams для апгрейду/даунгрейду підписки з prorationMode.

Чому серверна верифікація обов'язкова?

Ніколи не довіряйте лише клієнтському коду при розблокуванні платного контенту. Клієнтська верифікація обходиться модифікацією додатку.

Для IAP мінімальна схема: додаток отримує receiptData (iOS) або purchaseToken (Android), відправляє на бекенд, бекенд верифікує через Apple App Store Server API / Google Play Developer API, зберігає статус у БД, віддає відповідь клієнту. RevenueCat робить це за вас — але якщо у вас кастомний бекенд, потрібно реалізувати самостійно.

Webhook-и важливіші, ніж здається. Користувач може скасувати підписку через налаштування телефону, не через додаток — додаток не отримає про цю подію в реальному часі. Тільки webhook від Apple/Google (або RevenueCat) дозволяє своєчасно оновити статус. Ми використовуємо перевірку підпису вхідних запитів через Apple's signedPayload та Google's DeveloperNotification.

Як RevenueCat спрощує інтеграцію?

Підтримувати StoreKit 2 та Google Billing одночасно, з урахуванням промо-кодів, оферт, відновлення покупок та серверної верифікації — це кілька місяців розробки. RevenueCat закриває більшу частину цього шару.

RevenueCat — не просто SDK для платежів. Це:

• Єдиний API для iOS та Android (і Stripe для вебу)
• Серверна верифікація та зберігання статусів підписок
• Webhooks на події (покупка, відновлення, скасування, billing issue)
• Аналітика по когортам, MRR, churn
• A/B тестування оферт через Experiments

Purchases.configure(withAPIKey:) при старті, Purchases.shared.getCustomerInfo() для отримання поточних entitlements — мінімальний інтегрований шар. Purchases.shared.purchase(package:) замість прямого виклику StoreKit/Billing.

У документації RevenueCat сказано: «RevenueCat handles receipt validation on the server side, reducing client-side complexity and preventing fraudulent purchases.»

Обмеження RevenueCat: платний (безкоштовно до певного рівня MRR, далі відсоток від доходу), не підходить для дуже складних flow з кількома storefront-ами або кастомними bundle-ами. Однак для типового SaaS-додатку економія на власній розробці є значною — інтеграція окупається швидко.

Stripe в мобільних додатках

Stripe — для оплати фізичних товарів, послуг, B2B-платежів де IAP не вимагається політикою платформи.

Stripe iOS SDK та Android SDK — PaymentSheet для готового UI оплати, PaymentSheetFlowController для кастомного UI зі збереженими картками. Payment Intent створюється на сервері, client secret передається в додаток — карткові дані ніколи не проходять через ваш сервер, лише через Stripe.

Apple Pay та Google Pay через Stripe: PKPaymentRequest (iOS) та GooglePayLauncher (Android) вже інтегровані в Stripe SDK. Конверсія у Apple Pay дає в 1.3–2 рази вищий результат, ніж форми з ручним введенням картки — це цифри, які ми підтвердили на десятці проєктів.

Збережені картки через SetupIntent + Customer API — користувач платить в один тап при повторному візиті. Compliance: PCI DSS SAQ A — найлегший рівень compliance, оскільки Stripe Tokenization прибирає потребу зберігати карткові дані на своїй стороні. Згідно з PCI DSS, передача токенів звільняє від необхідності сертифікації рівня 1.

3DS2 (Strong Customer Authentication) — обов'язковий для платежів у ЄС за PSD2. Stripe обробляє автоматично через PaymentIntent.confirmPayment, але потрібно коректно обробити .requiresAction статус та повернути користувача на потрібний екран після аутентифікації.

Що входить в роботу (deliverables)

Процес та терміни

Починаємо з з'ясування бізнес-моделі: підписки, разові покупки, consumables, freemium. Від цього залежить архітектура. Тестування IAP вимагає Sandbox-акаунтів (Apple) та License Testers (Google) — це окреме налаштування середовища.

Sandbox Apple поводиться не так, як production: підписки відновлюються кожні 5 хвилин замість місяця, inGracePeriod працює по-іншому. Обов'язково тестувати сценарії: закінчення тріалу, скасування, billing retry, refund.

Як налаштувати тестове середовище для платежів?

Вартість розраховується індивідуально виходячи з набору інструментів та складності серверної логіки. У середньому ми вкладаємося в бюджет, який обговорюється окремо, але економія від запобігання помилок та churn окупає ці вкладення за 2–3 місяці.

Отримайте консультацію по вашому проєкту — зв'яжіться з нами. Ми допоможемо обрати оптимальну архітектуру платежів, яка пройде рев'ю сторів та не зламається при пікових навантаженнях.