ZeonTools
What is an Apple Wallet .pkpass file?
A .pkpass file is the standard file format used by Apple Wallet (and widely supported by Google Wallet/Google Pay apps). Despite the unique extension, a .pkpass file is simply a standard ZIP archive. Inside this archive, there are no HTML or CSS files—only raw image assets (like logo.png, icon.png, strip.png) and a strict pass.json manifest file.
Apple's iOS parses this JSON file natively and uses native Swift UI components to render the digital card on the user's screen. Because you cannot use custom CSS in a real Wallet Pass, building the JSON structure visually using an architect tool is critical to ensure your typography, transit icons, and colors look correct before deployment.
Geofencing & Lock Screen Triggers
One of the most powerful contextual features of Apple Wallet is its ability to trigger notifications based on the user's physical location. By supplying a locations array in your pass.json, you can define specific GPS Latitude and Longitude coordinates.
When the user's iOS device enters the radius of these coordinates (a geofence), iOS will automatically display the pass on the user's Lock Screen alongside the relevantText you define (e.g., "Welcome to SFO Airport! Tap to access your boarding pass."). This provides immense UX value without requiring the user to download a full native application.
The pass.json Architecture Anatomy
The pass.json dictionary is highly structured. At the root, you define your Apple Developer teamIdentifier, the passTypeIdentifier, and visual strings like logoText, backgroundColor, and foregroundColor.
Inside the root, you must declare a dictionary mapping to the "Style" of the pass (e.g., boardingPass, coupon, storeCard). Inside that specific dictionary, you define Arrays of Fields: Primary Fields (large header text), Secondary Fields (medium text), Auxiliary Fields (small text), and Back Fields (metadata displayed when the user taps the info button).
Transit Types & Layout Constraints
Different pass types have different layout constraints hardcoded into iOS. For example, if you build a boardingPass, Apple's JSON specification strictly requires you to define a transitType (e.g., PKTransitTypeAir, PKTransitTypeTrain, or PKTransitTypeBoat).
This tells the OS to render the corresponding transit icon between the Primary fields. If you choose a storeCard or coupon, you cannot use transit types, and the card layout relies heavily on a central strip.png image rather than a split primary header.
Cryptographic Compilation (How to Deploy)
You cannot simply ZIP a pass.json and email it to an iPhone. Apple strictly enforces cryptographic security to prevent malicious or spoofed passes. To compile the pass, you must first generate a manifest.json containing the SHA1 hash of every file in the directory.
Then, you use your Apple Developer Pass Type ID Certificate and the Apple WWDR Intermediate Certificate to cryptographically sign that manifest, generating a detached PKCS#7 signature file (literally named signature). Finally, you ZIP the payload together. Our Compiler CLI tab provides the exact OpenSSL commands for this process.
Push Notifications & Live Updates (APNs)
One of the most powerful features of Apple Wallet is live updates (e.g., changing a flight gate or updating a loyalty point balance). To enable this, your pass.json must include a webServiceURL (pointing to your HTTPS API endpoint) and an authenticationToken.
When the user installs the pass, Apple Wallet automatically makes a POST request to your API to register the device. When you need to update the pass, your backend sends an Apple Push Notification (APN) to the device. The device silently wakes up, hits your webServiceURL to download the new .pkpass bundle, and dynamically updates the UI.