Skip to content
Help Center Guide · Wallet Integrations
3 min readVerified 2026-11-16

Platform Differences & Limitations

Compare Apple Wallet, Google Wallet, and conditional Samsung Wallet capabilities — lock-screen messages, geofencing caps, and field zones.

In This Guide

Architectural Comparison: Apple Wallet vs. Google Wallet

While Passinstance provides a unified template designer and REST API that abstracts platform complexity, Apple Wallet and Google Wallet differ fundamentally in how passes are packaged, styled, updated, and metered at the OS level:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
DUAL-WALLET SERIALIZATION & SYNC DIVERGENCE
STAGE 01 UNIFIED PASSINSTANCE TEMPLATE & PASS RECORD
Single Template Schema + Dynamic Attributes + Mechanic State Engine
Apple Wallet Serializer
STAGE 02A
Artifact: Signed .pkpass ZIP bundle
Colors: Strict rgb(r, g, b) format
Layout: Fixed Front + Flip Back Card
Rich Text: <a> tags in Back Fields
Sync: APNs Empty Push {}Pull
Metering: Per Device (iPhone + Watch)
Google Wallet Serializer
STAGE 02B
Artifact: Cloud Class + Object
Colors: Hexadecimal #RRGGBB
Layout: Vertical Scrolling View
Rich Text: Structured `Google Walle
Sync: Direct Cloud REST PATCH
Metering: Per Unique Pass Object

Detailed Technical Comparison Matrix

Feature / Technical ConstraintApple Wallet (iOS & watchOS)Google Wallet (Android)Samsung Wallet (Partner-Gated)
Delivery ArtifactSigned .pkpass ZIP archive (application/vnd.apple.pkpass)RS256-signed Save JWT URL (https://pay.google.com/gp/v/save/<jwt>) + Cloud REST ObjectPartner-gated card reference (samsungWalletCardId, samsungWalletRefId)
Color SerializationMust be rgb(r, g, b) (hex and alpha channels rejected by iOS)Hexadecimal #RRGGBB (hexBackgroundColor)Hexadecimal #RRGGBB
Field Layout Zones6 discrete zones: header, primary, secondary, auxiliary, back, footerVertical sections: cardTitle, subheader, header, textModulesData (rows), linksModuleDataVendor template slots
HTML / Clickable LinksPermitted only in backFields via attributedValue (<a href="..."> tags only)Rendered via dedicated linksModuleData.uris array (uri, description)Dedicated link fields
Update & Push ProtocolTwo-step: APNs HTTP/2 silent push ({} payload, max 4096 bytes) wakes iPhone to pull GET /v1/passes/...Single-step: Server executes REST PATCH on walletobjects/v1/...; Google Play Services pushes to phoneProvider REST API
Lock-Screen Alert TriggerField value changes on a field defining changeMessage: "... %@"notifyPreference: "NOTIFY_ON_UPDATE" or addMessage (TEXT_AND_NOTIFY, max 3 per 24h)Not enabled as primary push surface
Active Pass MeteringPer registered deviceLibraryIdentifier (1 iPhone + 1 paired Apple Watch = 2 registrations)Deduplicated per unique <issuerId>.<objectId> across all Android devices signed into the same Google AccountAccount-scoped where enabled
Geofencing & BeaconsUp to 10 GPS coordinates (locations) + up to 10 BLE iBeacons (beacons) per .pkpassUp to 10 GPS coordinates on Class/Object (locations note: deprecated/restricted by Google in newer Play Services)Device-dependent
Deletion TelemetryImmediate DELETE /v1/devices/:deviceLibId/registrations/... call when removed from WalletImmediate POST /api/v1/wallet/callback with eventType: "del"Limited telemetry
Contactless NFC ProtocolApple VAS (ISO/IEC 14443 Type A/B, ECDH P-256, requires Apple NFC entitlement)Google Smart Tap (NFC_SMART_TAP, collectorId, ECDH P-256)Not supported

Important: Do not treat Samsung Wallet as globally identical to Apple Wallet and Google Wallet across every region and workspace. While Passinstance API maintains schema fields (samsungWalletCardId, samsungWalletRefId) for Samsung integrations, Samsung Wallet requires partner-gated onboarding per region — inspect Samsung Wallet Support Scope for eligibility details.

Platform-Specific Design & Payload Rules

1. Color Conversion & Contrast Enforcement

Apple's PassKit parser rejects .pkpass archives if backgroundColor, foregroundColor, or labelColor contains a #RRGGBB hex string or an rgba() alpha channel. Passinstance stores normalized color models (Color) and automatically serializes rgb(r, g, b) for Apple .pkpass generation while emitting #RRGGBB for Google Wallet classes.

2. HTML Anchor Restrictions in attributedValue

In Apple Wallet, clickable hyperlinks, phone numbers (tel:), and mailto links are supported exclusively on the back of the pass (backFields) using the attributedValue property. Apple strips all HTML tags except <a href="...">...</a>. On Google Wallet, Passinstance maps these links into the structured linksModuleData section at the bottom of the scrolling pass view:

JSON
{
  "appleBackField": {
    "key": "website",
    "label": "TERMS & CONDITIONS",
    "value": "https://yourbrand.com/terms",
    "attributedValue": "<a href=\"https://yourbrand.com/terms\">View Terms & Conditions</a>"
  },
  "googleLinksModule": {
    "uris": [
      {
        "uri": "https://yourbrand.com/terms",
        "description": "View Terms & Conditions",
        "id": "link_terms"
      }
    ]
  }
}

3. Multi-Device Registration Counts (iPhone + Apple Watch)

When an iPhone owner with a paired Apple Watch installs an Apple Wallet pass, iOS and watchOS each register an independent deviceLibraryIdentifier and APNs pushToken against POST /v1/devices/.../registrations/.... Passinstance tracks both installedDevices (total push endpoints) and uniqueDevices in the Analytics Dashboard so you can distinguish unique passholders from multi-device installations.

Review Apple Wallet, Google Wallet, and Template Design & Configuration for layout best practices.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.