iOSPaymentsTutorial

Implementing Alternate Billing Systems on iOS for India: A Technical Guide

UUnknown

2026-03-08

10 min read

A hands-on 2026 runbook to add alternate billing on iOS for India—secure, App Store–compliant, and testable.

Stop wasting cycles on fragmented billing: implement alternate payments on iOS for India without breaking the App Store or UX

If you ship apps for Indian users, you face two hard realities in 2026: regulators are pushing for alternative payment flows, and Apple still enforces App Store rules that can invalidate an app if you implement them incorrectly. This guide gives a practical, step-by-step runbook for engineering teams to add and test alternate billing systems on iOS for India — from detecting entitlements and region, to secure server-side validation, UX guardrails, and testing strategies that pass review.

Why this matters now (2026 snapshot)

Late 2024 through 2026 saw accelerating regulatory pressure worldwide to open platform payment systems. India alone has had multiple enforcement actions and rule changes; the Competition Commission of India (CCI) warned Apple in January 2026 about delays in an antitrust investigation tied to in-app payments. That context means many apps operating in India must support at least one alternative billing path to comply with evolving rules while preserving revenue, security, and user trust.

At the same time, Indian payment rails continue to evolve: UPI is ubiquitous, wallets and BNPL are mainstream, and major PSPs (Razorpay, Cashfree, PayU, Stripe India) provide SDKs tailored to local requirements. Your implementation must be compliant, testable, and resilient to App Store review.

High-level approach: safe, compliant, and testable

Detect eligibility: determine whether a user can be shown alternative billing on iOS (country, app version, Apple allowances).
Design dual flows: maintain StoreKit purchase flow, and add an alternative payment flow that’s shown only when legally permitted.
Server-side truth: perform receipt/token validation and reconciliation on your server for both flows.
UX guardrails: never provide disallowed prompts or explicit external purchase incentives in App Store builds unless regionally permitted.
Test hard: sandbox StoreKit + manage staged alternate payments with mocks and end-to-end tests using test PSP environments.

Step 1 — Determine if alternative billing is allowed and for which users

Start with a strict gating mechanism. For India you should check three signals:

Locale / region: avoid client-side IP spoofing assumptions by using server-side determination. Device locale is useful as UI hint only.
Apple allowance: Apple’s policy and any region-specific entitlement (for example, an entitlement Apple provides when alternate billing is allowed) — fetch a server-side policy file that you can toggle quickly for App Store review responses.
Contractual/merchant onboarding status: whether your company is onboarded with PSPs and has necessary KYC for Indian operations.

Example flow: on app launch, call GET /v1/policy?platform=ios&country=IN — server returns flags like allowAlternateBilling, allowedPSPs, displayTextConstraints.

Client-side sample (Swift) — request policy

struct BillingPolicy: Decodable {
  let allowAlternateBilling: Bool
  let allowedPSPs: [String]
}

func fetchBillingPolicy(completion: @escaping (BillingPolicy?) -> Void) {
  let url = URL(string: "https://api.example.com/v1/policy?platform=ios&country=IN")!
  URLSession.shared.dataTask(with: url) { data,_,_ in
    guard let d = data else { completion(nil); return }
    completion(try? JSONDecoder().decode(BillingPolicy.self, from: d))
  }.resume()
}

Step 2 — Implement a dual-purchase architecture

You must keep StoreKit (App Store billing) as the canonical in-app route. The alternate route should be a parallel, well-contained flow that doesn't interfere with purchases through StoreKit. Recommended architecture:

PurchaseManager (client): abstracts both StoreKit and AlternatePaymentManager
AlternatePaymentManager (client): handles PSP SDKs or web checkout, callback handling, and shows proper UI
Server-side Purchase API: receives app-originated requests for both StoreKit receipts and PSP confirmations, reconciles, issues entitlement JWTs

Key constraints to maintain App Store compliance

Do not include explicit external purchase prompts in regions where Apple prohibits them. Use server-side flags to show/hide UI.
When alternate billing is allowed, follow Apple’s display rules: labels, disclosure copy, and the option to use App Store payments must be presented if required.
Keep the StoreKit flow intact and accessible unless Apple explicitly permits otherwise for that user/region.

Step 3 — Integrate a PSP: patterns for SDK and web-based flows

Most Indian PSPs offer two integration models:

Native SDKs (Razorpay, Cashfree) — fast UX, Crashlytics, and device-level tokenization.
Web checkout (hosted pages/UIn-webview or SFSafariViewController) — simpler compliance for dynamic flows and 3DS/SCA.

Best practice: use SFSafariViewController or ASWebAuthenticationSession for web checkouts to preserve security and cookies while avoiding disallowed in-app browsers.

Example: launching a web checkout and handling callback

// Launch checkout in SFSafariViewController
let checkoutURL = URL(string: "https://checkout.example-psp.com/pay?order_id=12345")!
let safari = SFSafariViewController(url: checkoutURL)
present(safari, animated: true)

// PSP redirects to your universal link: myapp://checkout/complete?order=12345&status=success
// Handle in SceneDelegate or AppDelegate via continue userActivity or openURL

Step 4 — Server-side reconciliation and receipts

The server must be the single source of truth for purchase state. For alternate flows, the server should:

Receive PSP webhook events (payment_intent.succeeded, order.completed).
Validate the webhook signature using PSP-provided secrets.
Map PSP payments to product SKUs identical to your StoreKit SKUs.
Issue and store entitlement tokens (JWT) enabling the app to unlock content.
Allow users to link purchases to Apple receipts later, if required for audit or refunds.

Server pseudo-endpoints (recommended)

POST /v1/purchases/psp-confirm
  { order_id, psp_id, psp_signature }

POST /v1/purchases/appstore-validate
  { receiptData }

GET /v1/user/entitlements
  returns list of active purchases and source (psp|appstore)

Step 5 — Receipt strategy and idempotency

Receipt handling differs between StoreKit and alternate flows. Key recommendations:

For App Store purchases, validate StoreKit receipts server-side (App Store verifyReceipt API) and cache result with an expiration.
For PSP purchases, verify webhook signatures and confirm payment status with the PSP API before issuing entitlements.
Use idempotency keys for all server-side purchase confirmations to avoid double-granting entitlements.
Keep a unified purchase ledger that records: user_id, product_id, source, transaction_id, timestamp, and server-validated status.

Step 6 — UX patterns and compliance-ready copy

UX mistakes get apps rejected. Follow these rules:

Only show alternate payment options when the server flag allows it for that user.
When required, present Apple's App Store payment as an alternative (if regulators or agreements demand parity).
Use neutral language: “Choose a checkout method” rather than “Save money with our external checkout”.
Disclose refund and subscription terms consistently across both flows.

Rule of thumb: conservative, transparent UI copy + server-side gating = fewer App Review rejections.

Step 7 — Security, privacy and regulatory compliance

Security and compliance are non-negotiable:

PCI DSS: avoid storing raw card data — rely on PSP tokenization.
Data residency: many Indian payments require local data storage for KYC and settlement — make your infra compliant.
Authentication: use JWTs signed with rotating keys for entitlements. Short-lived tokens reduce risk.
IDS & monitoring: log payment events and set alerts for failed reconciliations or duplicate grants.

Step 8 — Testing matrix and tools

Test across these vectors:

StoreKit sandbox purchases (auto-renewing subscriptions, non-consumables, consumables).
PSP sandbox environments — test success, failure, pending, 3DS flows, and webhooks.
Network failure and retry handling — simulate using tools like Charles and network link conditioners.
App Review simulations — disable alternate billing via server policy and verify flows still enable StoreKit purchases.
Edge cases — account merges, device restores, refunded PSP payments, chargebacks.

Automated tests to include

Unit tests for PurchaseManager with injected mocks for StoreKit and PSP clients.
Integration tests for server endpoints using PSP sandbox webhooks.
UI tests verifying gating and copy when policy flags flip.

Step 9 — Handling refunds, disputes and customer support

Operational playbook:

Map PSP transaction IDs to internal order IDs and store webhook history for dispute resolution.
Provide customer support tools that accept StoreKit receipts or PSP reference IDs to look up purchase state.
Automate reconciliation jobs that compare PSP reports with your ledger daily to catch misses early.

Monitoring and metrics

Track these KPIs to see if alternate billing is healthy:

Conversion rate by channel (App Store vs PSP)
Chargeback/refund rate by PSP
Time-to-entitlement (ms) after payment confirmation
App Review issues triggered by billing UI

2026 trends and future-proofing

Expect more regulatory fragmentation in 2026–2027. Practical predictions and how to prepare:

More region-based entitlements: Platforms will likely expose finer grained APIs to indicate when alternate billing is allowed. Keep policy toggles and feature flags centralised on your server.
Open billing standards: Look for industry initiatives to standardize payment integration across app stores; design your PurchaseManager to plug into a standard interface.
Token-first UX: tokenized wallets and UPI intent flows will reduce friction — support deep links and intent APIs from PSPs.
Receipt normalization: expect the rise of JSON/JWT receipts across PSPs and app stores — build your entitlement service to accept multiple receipt formats and produce a single entitlement token.

Real-world example: integrating Razorpay + StoreKit for a subscription product

Actionable checklist:

Onboard Razorpay and configure webhook endpoints / API keys.
Add server endpoint POST /create-order that creates a Razorpay order for given product_id and user_id, returns order_id and checkout token.
Client opens SFSafariViewController or Razorpay iOS SDK to complete payment.
Razorpay calls your webhook; server validates signature and updates ledger; server issues entitlement JWT.
Client polls GET /v1/user/entitlements and receives entitlement enabling features.

Server pseudo-workflow

// 1. create-order
POST /create-order
{ user_id, product_id }
// server -> Razorpay: create order
// resp -> { order_id, checkout_token }

// 2. PSP webhook
POST /webhook/razorpay
{ event, payload }
// server validates signature, then marks order paid and issues entitlement token

// 3. client polls
GET /user/entitlements -> { active: [ {sku: "pro_monthly", source: "razorpay", token: "jwt..."} ] }

Common pitfalls and how to avoid them

Failing App Review because the alternate option is shown without server-side gatekeeping — always feature-flag it server-side.
Trusting client-side country detection — use server-side geo-IP/KYC confirmations for entitlement decisions.
Not reconciling webhooks — lead to phantom grants or unrecoverable chargebacks.
Storing card data — avoid this and rely on PSP tokenization to stay out of PCI scope.

Checklist before you ship

Server policy flags in place to enable/disable alternate billing per region.
Complete PSP sandbox integration and webhook validation working.
StoreKit sandbox verification done and receipts are validated server-side.
UI copy reviewed for App Store requirements and legal team sign-off for disclosures.
Automated and manual tests for success/fail/pending cases across both flows.
Operational playbooks for refunds, disputes, and App Review communications.

Advanced strategies and optimizations

Once stable, consider these advanced techniques:

Hybrid entitlements: let users buy via PSP, then offer an option to map that purchase to their Apple account for continuity when switching devices.
Smart routing: route high-value transactions through the most reliable PSP based on realtime success metrics.
Analytics-driven UX: A/B test checkout UI and copy to find the optimal conversion that remains compliant.
Open standards participation: engage with industry groups building standard billing APIs — early adopters benefit from mature tooling.

Final recommendations

Implement alternate billing in India with a server-first, policy-gated approach that preserves the App Store StoreKit flow, prioritizes security and reconciliation, and keeps UX and support workflows unified. In 2026 the regulatory landscape is fluid — keep feature flags, logs, and rapid rollback paths ready.

Actionable takeaways (quick reference)

Server-side policy flags control regional alternate billing availability.
Maintain StoreKit; add alternate flow only when allowed and shown by server policy.
Use SFSafariViewController or PSP SDKs; never handle raw payment card data.
Validate receipts/webhooks server-side and issue unified entitlement tokens.
Comprehensively test sandbox StoreKit and PSP environments and monitor reconciliation daily.

Call-to-action

If you want a ready-to-run starting point, grab our open-source reference implementation on GitHub (Server + iOS sample) that includes feature flags, PSP webhook handlers, and StoreKit validation scripts — tailored for India in 2026. Need a review of your billing architecture before App Review? Contact our engineering docs team for a 30‑minute audit and a compliance checklist you can present to legal and product.

Unknown

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.