Skip to content
Help Center Guide · Wallet IntegrationsOnboarding Phase 4
3 min readVerified 2026-11-16

Apple Wallet

How Passinstance generates .pkpass archives, signs with PKCS#7, registers iOS/watchOS devices, and handles Web Service callbacks.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Dual-Wallet live pass preview (Zoomed)

Toggle between Apple and Google in the Pass preview panel to confirm artwork, balance formatting, QR code legibility, and field alignment.

Overview: How Apple Wallet Integration Works

Passinstance generates native Apple Wallet .pkpass bundles (Apple Wallet Packager) conforming to Apple's PassKit package specification for iOS and watchOS. Every pass is assembled on the fly as a cryptographically signed ZIP archive delivered with the application/vnd.apple.pkpass MIME type.

Apple Wallet vs Google Wallet live pass preview
Apple Wallet vs Google Wallet live pass preview
SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
APPLE WALLET .PKPASS PACKAGING & WEB SERVICE
STAGE 01 PKPASS ARCHIVE BUILDER (Apple Wallet Packager)
1
Serialize pass.json (formatVersion: 1, rgb(r,g,b) colors, fields, NFC)
2
Hydrate Retina Assets (icon.png, logo.png, strip.png @1x / @2x / @3x)
3
Compile Localization Bundles (<lang>.lproj/pass.strings in UTF-8)
4
Compute SHA-1 Checksum DictionaryWrite manifest.json
5
Generate Detached PKCS#7 signature (Pass Type Cert + Apple WWDR G4/G6)
6
Compress ZIP ArchiveStream as Content-Type: application/vnd.apple.pkpass
STAGE 02 APPLE WALLET WEB SERVICE PROTOCOL (/v1)
Register Device: POST/v1/devices/:deviceLibId/registrations/:typeId/:sn
Poll Updated List: GET/v1/devices/:deviceLibId/registrations/:typeId
Download Bundle: GET/v1/passes/:passTypeId/:serialNumber
Unregister Pass: DELETE/v1/devices/:deviceLibId/registrations/:typeId/:sn
Client Error Log: POST/v1/log

Internal Structure of a .pkpass Archive

An Apple Wallet .pkpass bundle is a standard ZIP archive containing five core structural layers:

File / DirectoryFormat & EncodingRole in Apple Wallet
pass.jsonUTF-8 JSONDefines pass style (storeCard, coupon, eventTicket, boardingPass, generic), passTypeIdentifier, teamIdentifier, serialNumber, authenticationToken, webServiceURL, fields, barcodes, locations, and nfc dictionary.
Visual Assets (.png)PNG (@1x, @2x, @3x)Up to 13 template image slots hydrated into Apple PassKit filenames (icon.png, logo.png, strip.png, thumbnail.png, background.png, footer.png, artwork.png, venueMap.png) across retina resolutions.
<lang>.lproj/pass.stringsUTF-8 Strings TableLocalized key-value translations (e.g., de.lproj/pass.strings, fr.lproj/pass.strings) matched against the iPhone's system locale.
manifest.jsonUTF-8 JSONFlat dictionary mapping every relative file path in the bundle (excluding manifest.json and signature) to its 40-character hexadecimal SHA-1 hash.
signatureBinary DER (PKCS#7)Detached PKCS#7 cryptographic signature of manifest.json, signed by your Apple Pass Type ID private key and chaining to the Apple WWDR G4/G6 intermediate certificate.

Important: Apple Wallet strictly requires color values in pass.json (backgroundColor, foregroundColor, labelColor) to be serialized as rgb(r, g, b) strings. Passinstance's apple-pass-field.serializer.ts automatically converts hex values to rgb(r, g, b) and strips alpha channels so iOS never rejects a bundle during signature and schema verification.

Example pass.json Payload Structure

JSON
{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.yourbrand.loyalty",
  "serialNumber": "PI-8849-2026-X9",
  "teamIdentifier": "9A8B7C6D5E",
  "organizationName": "Phenix Roasters",
  "description": "Phenix VIP Rewards Card",
  "webServiceURL": "https://api.passinstance.com",
  "authenticationToken": "b7f9e2c1a4d80931f6e5c2b8a1049d7e",
  "foregroundColor": "rgb(255, 255, 255)",
  "backgroundColor": "rgb(18, 24, 38)",
  "labelColor": "rgb(148, 163, 184)",
  "storeCard": {
    "headerFields": [
      {
        "key": "tier",
        "label": "TIER",
        "value": "Gold"
      }
    ],
    "primaryFields": [
      {
        "key": "points",
        "label": "POINTS BALANCE",
        "value": 1450,
        "changeMessage": "Your points balance updated to %@"
      }
    ],
    "backFields": [
      {
        "key": "support_link",
        "label": "MEMBER PORTAL",
        "value": "Visit https://yourbrand.com/member",
        "attributedValue": "<a href=\"https://yourbrand.com/member\">Open Member Portal</a>"
      }
    ]
  },
  "barcodes": [
    {
      "format": "PKBarcodeFormatQR",
      "message": "PI-8849-2026-X9",
      "messageEncoding": "iso-8859-1",
      "altText": "PI-8849-2026-X9"
    }
  ]
}

Apple Wallet Web Service Endpoints (/v1)

Every live pass contains webServiceURL and a minimum 16-character authenticationToken. iOS and watchOS devices communicate directly with Passinstance's /v1 endpoints using the HTTP header Authorization: ApplePass <authenticationToken>:

MethodEndpoint PathHTTP StatusesPurpose
POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber201 Created, 200 OK, 401 UnauthorizedRegisters the iPhone or Apple Watch pushToken for APNs updates and marks the pass installed.
GET/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier200 OK, 204 No ContentReturns { serialNumbers: [...], lastUpdated: "<tag>" } for passes modified since ?passesUpdatedSince=.
GET/v1/passes/:passTypeIdentifier/:serialNumber200 OK, 304 Not Modified, 401 UnauthorizedGenerates and streams the latest signed .pkpass bundle when woken by an APNs push or manual pull-to-refresh.
DELETE/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber200 OK, 401 UnauthorizedUnregisters the device when the passholder deletes the pass from Apple Wallet.
POST/v1/log200 OKReceives diagnostic { "logs": [...] } arrays from iOS devices if a .pkpass fails client-side validation.

Explore further technical specifications at Apple Wallet Platform, Apple Wallet Certificates, and Apple VAS Contactless Protocol.

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.