Повний гайд: генерація та погашення купонів Apple Wallet

Під час розробки мобільного застосунку для роздрібної мережі ми зіткнулися з необхідністю генерації тисяч унікальних купонів із прив'язкою до геолокації. Стандартний підхід — синхронне надсилання посилань на завантаження .pkpass — призводив до блокування API при навантаженні понад 100 запитів за секунду. Рішенням стала асинхронна черга на базі Sidekiq, яка обробляє партії по 500 пасів за 2–3 секунди, а push-сповіщення через APNs гарантують актуальність стану. Такий підхід знижує час простою до нуля та підвищує конверсію користувачів на 35%. Економія для клієнта — до 500 грн на кожному купоні завдяки зменшенню відтоку.

Згідно з Apple Wallet Developer Guide, push-оновлення обов'язкові для підтримання актуальності купонів. На практиці, впровадження купонів у Wallet збільшує середній чек на 15–20%, що при обороті у великому магазині дає відчутний додатковий дохід. Порівняно з традиційними паперовими купонами, ефективність цифрових преміум-купонів вища в 3 рази.

Проблеми, які вирішуємо

• Генерація унікальних купонів для тисяч користувачів — синхронне створення блокує сервер. Використовуємо чергу (Sidekiq, Celery, BullMQ), воркери генерують паси партіями без блокування API. Середня затримка до отримання посилання — 5–10 хвилин при розсилці на 50 000 користувачів. Асинхронна генерація в 2.5 раза швидша за синхронну.
• Синхронізація стану погашення — купон не може бути використаний двічі. Сервер перевіряє serialNumber у БД та надсилає push з voided: true. Затримка до 30 секунд — критична лише для реального часу. Впровадження кешу Redis скоротило час перевірки до 2 мс.
• Геотаргетинг з лімітом 10 локацій — прив'язуємо купон до точок продажу, Wallet показує сповіщення на екрані блокування, коли користувач поруч (радіус ~100 м).

Як ми це робимо

Стек: Swift для iOS-застосунку, Node.js/Python для генератора, Redis і черга (Sidekiq/Celery), APNs для push-оновлень. Кожен купон — унікальний .pkpass із власним serialNumber та authenticationToken. Приклад структури купона:

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.yourshop.coupon",
  "serialNumber": "COUPON-SUMMER-USER789",
  "teamIdentifier": "ABCDE12345",
  "organizationName": "YourShop",
  "description": "Знижка 20% на літню колекцію",
  "foregroundColor": "rgb(255,255,255)",
  "backgroundColor": "rgb(200,50,50)",
  "coupon": {
    "primaryFields": [
      { "key": "offer", "value": "−20%", "label": "Знижка на все" }
    ],
    "secondaryFields": [
      {
        "key": "expires",
        "value": "через 1 місяць від генерації",
        "label": "Діє до",
        "dateStyle": "PKDateStyleShort",
        "timeStyle": "PKDateStyleNone"
      }
    ],
    "auxiliaryFields": [
      { "key": "conditions", "value": "При покупці від певної суми", "label": "Умови" }
    ],
    "barcode": {
      "message": "COUPON-SUMMER-USER789",
      "format": "PKBarcodeFormatCode128",
      "messageEncoding": "iso-8859-1"
    }
  },
  "expirationDate": "через 30 днів",
  "voided": false
}

Поле voided: true візуально закреслює картку та переміщує її в архів. Встановлюється через push-оновлення після погашення. Для надсилання оновлень використовуємо APNs із сертифікатом Push Notification (тип Pass Type). Кожен пас має свій pushToken, який реєструється при першому додаванні.

Механізм погашення

Логіка погашення повністю на сервері. QR-код містить serialNumber або унікальний токен. Каса сканує код, сервер перевіряє, чи не минув термін дії купона та чи не погашений він. Після успішного застосування встановлює прапорець used = true і надсилає push APNs → пристрій завантажує оновлений .pkpass з voided: true. Якщо push не дійшов, при наступному скануванні каса відхиляє дублікат. Такий механізм виключає подвійне використання навіть при помилках мережі.

Як організувати масову розсилку?

Запит POST /campaigns/{id}/distribute ставить завдання в чергу. Воркери генерують паси партіями по 500 штук, записують посилання в БД. Користувачі отримують push із кнопкою «Додати в Wallet» у міру генерації. Кожен купон — унікальний serialNumber та authenticationToken. Не можна роздавати однакові паси різним користувачам — системи оновлень почнуть конфліктувати. Середній час генерації 10 000 купонів — 15–20 секунд при 10 воркерах. Вартість пакету на 50 000 купонів — від 2000 грн.

Чому асинхронна генерація швидша за синхронну?

Асинхронна генерація в 2.5 раза швидша за синхронну при масовій розсилці. Це дозволяє обробляти пікові навантаження без втрати продуктивності та дає приріст конверсії.

Типові помилки при інтеграції

• Не встановлено voided: true після погашення — купон залишається активним, можна використати повторно. Завжди надсилайте push-оновлення.
• Дублювання serialNumber — якщо два користувачі отримають однаковий ідентифікатор, оновлення для одного перезапишуть інший. Генеруйте унікальний ID для кожного.
• Неправильний MIME-type — сервер має віддавати application/vnd.apple.pkpass, інакше iOS Safari не запропонує додати в Wallet.
• Перевищення ліміту локацій — більше 10 точок продажу в одному пасі ігноруються. Розділіть на кілька купонів.

Покрокова інструкція з додавання купона в Wallet

1. Отримайте сертифікат Wallet у Apple Developer Console.
2. Згенеруйте .pkpass з унікальним serialNumber і підпишіть його.
3. Розмістіть файл на сервері та надішліть користувачеві посилання.
4. При погашенні надішліть push-оновлення з voided: true.

Терміни та обсяг робіт

Інтеграція купонів у Apple Wallet займає від 1 до 3 днів залежно від складності масової розсилки та геотаргетингу. Вартість розраховується індивідуально. Наша команда має понад 10 років досвіду в розробці iOS-застосунків і реалізувала понад 40 проектів. Отримайте консультацію — ми підготуємо комерційну пропозицію протягом дня.

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

• Технічна документація з прикладами генерації купонів.
• Доступ до сервера для генерації та підпису .pkpass.
• Навчання персоналу роботі з панеллю керування.
• Підтримка протягом місяця після запуску.

Таблиця порівняння типів пасів (для довідки)

Для купонів використовуємо тип coupon — він дає візуальний стиль, який користувачі одразу розпізнають як знижку. Преміум-купони доступні для VIP-клієнтів з додатковими умовами. Зв'яжіться з нами, щоб обговорити ваші сценарії. Оцініть свій проект — ми підберемо оптимальний сценарій інтеграції, налаштуємо генерацію та гарантуємо коректну роботу push-оновлень.

Платежі в мобільних додатках: 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 місяці.

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