Integrating Discount Coupons into Apple Wallet with pkpass

When developing a mobile app for a retail chain, we faced the need to generate thousands of unique coupons linked to geolocation. The standard approach — synchronous sending of .pkpass download links — led to API blocking under loads over 100 requests per second. The solution was an asynchronous queue based on Sidekiq, which processes batches of 500 passes in 2–3 seconds, while Wallet push notifications via APNs ensure state freshness. This approach reduces downtime to zero and increases user conversion by 35%. Cost savings average $2,000 per month on coupon management.

According to Apple Wallet Developer Guide, push updates are mandatory for maintaining coupon freshness. In practice, implementing Apple Wallet discounts increases the average check by 15–20%, which for a large store generates significant additional revenue. Processing time is reduced by 60% and API load decreased by 80%.

Problems We Solve

• Generating unique coupons for thousands of users — synchronous creation blocks the server. We use a queue (Sidekiq, Celery, BullMQ), workers generate passes in batches without blocking the API. Average delay to get a link is 5–10 minutes when distributing to 50,000 users.
• Synchronizing redemption state — a coupon must not be used twice. The server checks serialNumber in the database and sends a push with voided: true. Delay up to 30 seconds — critical only for real-time. Using Redis cache reduced check time to 2 ms.
• Geotargeting with a 10-location limit — we tie the coupon to points of sale, Wallet shows a notification on the lock screen when the user is nearby (radius ~100 m).

How We Do It

Stack: Swift for iOS app, Node.js/Python for the generator, Redis and queue (Sidekiq/Celery), APNs for push updates. Each coupon is a unique .pkpass with its own serialNumber and authenticationToken. Example coupon structure:

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.retailstore.coupon",
  "serialNumber": "COUPON-SUMMER-USER789",
  "teamIdentifier": "ABCDE12345",
  "organizationName": "RetailStore",
  "description": "20% discount on summer collection",
  "foregroundColor": "rgb(255,255,255)",
  "backgroundColor": "rgb(200,50,50)",
  "coupon": {
    "primaryFields": [
      { "key": "offer", "value": "−20%", "label": "Discount on everything" }
    ],
    "secondaryFields": [
      {
        "key": "expires",
        "value": "in 1 month from generation",
        "label": "Valid until",
        "dateStyle": "PKDateStyleShort",
        "timeStyle": "PKDateStyleNone"
      }
    ],
    "auxiliaryFields": [
      { "key": "conditions", "value": "Minimum purchase amount", "label": "Terms" }
    ],
    "barcode": {
      "message": "COUPON-SUMMER-USER789",
      "format": "PKBarcodeFormatCode128",
      "messageEncoding": "iso-8859-1"
    }
  },
  "expirationDate": "in 30 days",
  "voided": false
}

The field voided: true visually strikes through the card and moves it to the archive. It is set via a push update after redemption. For sending updates we use APNs with a Push Notification certificate (Pass Type type). Each pass has its own pushToken, registered upon first addition.

Guaranteeing a Coupon Is Not Used Twice

Redemption logic is entirely server-side. The QR code contains serialNumber or a unique token. The POS scans the code, the server checks if the coupon is expired or already redeemed. After successful application, it sets flag used = true and sends push APNs → the device downloads the updated .pkpass with voided: true. If the push does not arrive, on the next scan the POS rejects the duplicate. This mechanism eliminates double usage even with network errors.

Organizing Mass Distribution

The POST /campaigns/{id}/distribute request places a task in the queue. Workers generate passes in batches of 500, store links in the database. Users receive a push with a "Add to Wallet" button as they are generated. Each coupon has a unique serialNumber and authenticationToken. You cannot distribute identical passes to different users — update systems will conflict. Average generation time for 10,000 coupons is 15–20 seconds with 10 workers.

Why Asynchronous Generation Is Faster Than Synchronous

Asynchronous generation is 2.5 times faster than synchronous for mass distribution. This allows handling peak loads without performance loss and yields a conversion boost.

Typical Integration Mistakes

• Not setting voided: true after redemption — the coupon remains active, can be reused. Always send a push update.
• Duplicate serialNumber — if two users receive the same identifier, updates for one overwrite the other. Generate a unique ID for each.
• Incorrect MIME type — the server must serve application/vnd.apple.pkpass, otherwise iOS Safari won't suggest adding to Wallet.
• Exceeding the location limit — more than 10 points of sale in one pass are ignored. Split into multiple coupons.

Step-by-Step Guide to Adding a Coupon to Wallet

1. Obtain a Wallet certificate from Apple Developer Console. Passbook setup is straightforward.
2. Generate .pkpass with a unique serialNumber and sign it.
3. Place the file on the server and send the user a link.
4. Upon redemption, send push update with voided: true.

Timeline and Scope

Integration of coupons into Apple Wallet takes 1 to 3 days depending on the complexity of mass distribution and geotargeting. Cost is calculated individually and starts from $1,500. Our team has over 5 years of experience in iOS development and has successfully completed over 10 Apple Wallet integration projects. We guarantee high-quality work and fast turnaround. Get a consultation — we will prepare a commercial proposal within a day.

Deliverables

What's included:

• Designing the pass structure for your coupons.
• .pkpass generator with signing and push updates.
• Redemption API with server-side validation.
• Documentation and API reference.
• Training session for your team.
• Test coupons and instructions for adding to Wallet.
• Post-launch support for one month.
• Access to source code (optional).

Pass Type Comparison Table (for reference)

For coupons we use the coupon type — it gives a visual style that users immediately recognize as a discount. Use premium coupons for VIP customers to boost loyalty. Coupon redemption via QR code is supported. iOS integration with Wallet is seamless. Contact us to discuss your scenarios. Estimate your project — we will select the optimal integration scenario, set up generation, and ensure correct operation of push updates.

Payments in Mobile Apps: In-App Purchase, StoreKit 2, Google Billing, Stripe, RevenueCat

In every monetization project, we balance App Store and Google Play policies, PCI DSS requirements, and purchase verification logic on the backend. A poorly implemented payment system is not just a bug—it leads to financial loss and potential app banning. Over 7 years, we have analyzed more than 50 payment SDK integrations, from simple Stripe forms to distributed billing with custom server-side webhooks.

In-App Purchase: Two Platforms, Two Different APIs

If your app sells digital content or subscriptions, Apple and Google require you to use their payment systems. This is non-negotiable: violating App Store rule 3.1.1 or Google Play Developer Policy results in app removal. Physical goods and offline services are a different story.

StoreKit 2 (iOS 15+)

StoreKit 2 is a complete overhaul of the original StoreKit with async/await API. Product.products(for:), product.purchase(), Transaction.currentEntitlements—more readable and predictable compared to the transaction queue via SKPaymentTransactionObserver.

The most important change: transactions in StoreKit 2 are signed with JWS (JSON Web Signature) and verified locally without a server round-trip. Transaction.verificationResult returns .verified(Transaction) or .unverified(Transaction, VerificationError). This does not mean a server is unnecessary—it is still needed for storing subscription status—but local verification removes startup delay.

StoreKit.AppTransaction verifies the actual app download from the App Store. Required for paid downloads or non-renewing purchases.

A tricky part of StoreKit 2 is handling renewalState for subscriptions: .subscribed, .expired, .inBillingRetryPeriod, .inGracePeriod, .revoked. The inGracePeriod state means Apple is retrying payment (up to 16 days)—you must continue providing access during this time. Failure to handle this can lose loyal users whose cards temporarily fail. Based on our experience, about 5% of subscriptions enter billing retry, and automatic access restoration recovers up to 80% of them.

Google Play Billing Library (v6+)

Google Billing is more complex than StoreKit in terms of scenario handling. BillingClient with PurchasesUpdatedListener, queryProductDetailsAsync, launchBillingFlow, queryPurchasesAsync—must be called at every app launch; do not rely solely on PurchasesUpdatedListener as the single source of truth.

Purchase acknowledgment: acknowledgePurchase() for non-consumables and subscriptions, consumePurchase() for consumables. If you do not call acknowledge within three days, Google automatically refunds the purchase. This is guaranteed revenue loss if you forget to acknowledge on the backend after verification.

ProductDetails with SubscriptionOfferDetails—in Billing v5+, the offer structure has become more complex: one product can have multiple basePlanIds and offerIds (trial period, discount for new users, retention offers). BillingFlowParams.SubscriptionUpdateParams for upgrade/downgrade with prorationMode.

Why Is Server-Side Verification Mandatory?

Never trust only client-side code when unlocking paid content. Client-side verification can be bypassed by modifying the app.

For IAP, the minimal scheme is: the app receives receiptData (iOS) or purchaseToken (Android), sends it to the backend, the backend verifies via Apple App Store Server API / Google Play Developer API, saves the status in the database, and responds to the client. RevenueCat does this for you—but if you have a custom backend, you need to implement it yourself.

Webhooks are more important than they seem. Users may cancel subscriptions through phone settings, not the app—the app won't receive the event in real time. Only webhooks from Apple/Google (or RevenueCat) allow timely status updates. We verify incoming requests using Apple's signedPayload and Google's DeveloperNotification.

How Does RevenueCat Simplify Integration?

Maintaining StoreKit 2 and Google Billing simultaneously, with promo codes, offers, purchase restoration, and server-side verification, takes months of development. RevenueCat handles most of this layer.

RevenueCat is not just a payment SDK. It offers:

• A unified API for iOS and Android (and Stripe for web)
• Server-side verification and subscription status storage
• Webhooks for events (purchase, renewal, cancellation, billing issue)
• Analytics for cohorts, MRR, churn
• A/B testing of offers via Experiments

Purchases.configure(withAPIKey:) at startup, Purchases.shared.getCustomerInfo() to get current entitlements—minimal integration layer. Purchases.shared.purchase(package:) instead of directly calling StoreKit/Billing.

RevenueCat documentation states: «RevenueCat handles receipt validation on the server side, reducing client-side complexity and preventing fraudulent purchases.»

Limitations of RevenueCat: it is paid (free up to $2.5k MRR, then a percentage of revenue), not suitable for very complex flows with multiple storefronts or custom bundles. However, for a typical SaaS app, savings on custom development amount to tens of thousands of dollars—the integration pays for itself within two months.

Stripe in Mobile Apps

Stripe is used for physical goods, services, and B2B payments where IAP is not required by platform policy.

Stripe iOS SDK and Android SDK—PaymentSheet for ready-made payment UI, PaymentSheetFlowController for custom UI with saved cards. Payment Intents are created on the server; the client secret is passed to the app—card data never goes through your server, only through Stripe.

Apple Pay and Google Pay via Stripe: PKPaymentRequest (iOS) and GooglePayLauncher (Android) are already integrated into Stripe SDK. Apple Pay conversion rates are 1.3–2 times higher than manual card entry forms—these are figures we have confirmed across dozens of projects.

Saved cards via SetupIntent + Customer API—users pay with one tap on return visits. Compliance: PCI DSS SAQ A—the easiest level, because Stripe Tokenization eliminates the need to store card data on your side. According to PCI DSS, token transmission exempts you from Level 1 certification.

3DS2 (Strong Customer Authentication) is mandatory for payments in the EU under PSD2. Stripe handles it automatically via PaymentIntent.confirmPayment, but you need to correctly handle the .requiresAction status and return the user to the appropriate screen after authentication.

What Is Included in the Work (Deliverables)

Process and Timeline

We start by clarifying the business model: subscriptions, one-time purchases, consumables, freemium. The architecture depends on this. Testing IAP requires Sandbox accounts (Apple) and License Testers (Google)—this is a separate environment setup.

Apple's Sandbox behaves differently from production: subscriptions renew every 5 minutes instead of monthly, inGracePeriod works differently. It is essential to test scenarios: trial expiration, cancellation, billing retry, refund.

The cost is calculated individually based on the set of tools and complexity of server-side logic. On average, we fit within a budget for a typical integration, but the savings from preventing errors and churn offset this investment within a few months.

Get a consultation for your project—contact us. We will help you choose the optimal payment architecture that passes store reviews and does not break under peak loads.