25 September 2026 · 0 views

How to Create a Custom Apple Wallet Pass on iPhone

How to Create a Custom Pass in the Apple Wallet App on iPhone

Apple Wallet functions beyond debit and credit transactions processed via Apple Pay. The iOS ecosystem allows users and organizations to create custom Apple Wallet passes to store digital credentials, access keys, loyalty programs, gym memberships, boarding passes, and event tickets.

Converting physical plastic cards and paper tickets into digital assets removes physical clutter and enables lock screen automation based on time and geographic coordinates. You can generate custom passes through no-code mobile apps, web-based pass builders, Apple Shortcuts automation, or Apple’s official PassKit framework using custom JSON, cryptographic signatures, and shell scripting.

Understanding Apple Wallet Pass Architecture

Apple Wallet handles passes using the .pkpass file format. A .pkpass file is a standard ZIP archive containing a structured manifest, visual assets, localized text strings, and a cryptographic signature. When iOS detects a MIME type of application/vnd.apple.pkpass, the operating system parses the package, verifies the signature against Apple’s Root Certificate Authority, and displays an ingestion preview.

pass.pkpass (ZIP Archive)
├── pass.json
├── manifest.json
├── signature
├── icon.png
├── icon@2x.png
├── icon@3x.png
├── logo.png
├── logo@2x.png
├── thumbnail.png (Optional)
├── background.png (Optional)
├── strip.png (Optional)
└── en.lproj/
    └── pass.strings (Optional)

The Structure of a `.pkpass` File

pass.json: The core configuration file. Defines data fields, barcodes, text labels, colors, relevant locations, dates, and pass type categorizations.
manifest.json: A JSON dictionary mapping every file inside the bundle to its SHA-1 cryptographic hash. Used by iOS to verify bundle integrity.
signature: A PKCS #7 detached digital signature generated by an Apple-issued Pass Type ID certificate. It signs the contents of manifest.json.
Visual Assets: Standard PNG images formatted for 1x, 2x (@2x), and 3x (@3x) Retina displays:
- icon.png: Displayed in notifications and email attachments (29x29 pt).
- logo.png: Displayed on the top-left corner of the pass face (160x50 pt).
- thumbnail.png: Displayed alongside text on generic passes (90x90 pt).
- strip.png: Full-width banner graphic for coupons and event tickets (375x123 pt for coupons; 375x98 pt for tickets).
- background.png: Full card background image for event tickets (180x220 pt).

Supported Pass Styles

Apple Wallet enforces strict layout templates based on the pass type defined in pass.json. Custom styling must conform to one of five supported schemas:

+-------------------------------------------------------------------------+
|                               PASS STYLES                               |
+-------------------+-----------------------------------------------------+
| Pass Style Key    | Primary Use Case                                    |
+-------------------+-----------------------------------------------------+
| generic           | Membership cards, library cards, ID badges          |
| boardingPass      | Airlines, trains, bus routes, ferry transportation  |
| coupon            | Retail discounts, vouchers, promotional offers      |
| eventTicket       | Concerts, sporting events, museum admissions        |
| storeCard         | Loyalty point accounts, gift cards, store credit    |
+-------------------+-----------------------------------------------------+

Generic (generic): All-purpose card layout with equal field distribution. Suitable when no specialized transit or ticket iconography is needed.
Boarding Pass (boardingPass): Requires a transitType declaration (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, PKTransitTypeGeneric). Emphasizes departure and arrival destinations with a directional arrow.
Coupon (coupon): Displays a large central discount or offer using the strip.png canvas.
Event Ticket (eventTicket): Prioritizes venue details, seat coordinates, gate numbers, and graphic strips or background art.
Store Card (storeCard): Displays account balances, loyalty tier standings, and primary account holder names above the secondary barcode.

Method 1: Creating Passes via Third-Party Mobile Apps (No-Code)

Third-party mobile utilities allow users to create custom .pkpass files directly on iOS without an Apple Developer account or command-line tools.

Top iOS Pass Creator Tools

Pass2U Wallet: Offers customizable field mapping, dynamic barcode rendering, a public community template repository, and location-based relevance triggers.
Pass4Wallet: Free utility without tracking. Supports all standard pass styles, custom color schemes, custom barcodes, and iCloud backup.
Wallet Creator: Generates generic and store cards with OCR scanning for physical plastic cards.

Step-by-Step Creation Flow

To add a custom card to Apple Wallet using Pass4Wallet or Pass2U Wallet:

[Select Pass Style] ──> [Scan/Input Barcode] ──> [Assign Labels & Fields] ──> [Attach Artwork] ──> [Add to Apple Wallet]

Install and launch the pass generation app from the iOS App Store.
Tap + to start a new pass design.
Select the target layout style: Store Card, Coupon, Event Ticket, Boarding Pass, or Generic.
Configure the barcode:
- Select the barcode format: QR Code, PDF417, Aztec, or Code 128.
- Use the iPhone camera to scan an existing physical card, or type the alphanumeric payload string into the Message field.
- Enter an optional Alternative Text string to display account numbers below the barcode image.
Populate pass fields:
- Header Field: Card name, business name, or pass title.
- Primary Field: Member name or account balance.
- Secondary Fields: Membership tier, expiration date, or issue date.
- Auxiliary Fields: Customer support telephone numbers or sub-account identifiers.
Configure visual elements:
- Set Background Color, Label Color, and Foreground (Text) Color using HEX values.
- Import a square image for icon.png and a rectangular brand asset for logo.png.
Tap Preview to verify the layout.
Tap Add to Apple Wallet (PKAddPassesViewController). The operating system renders the pass preview sheet. Tap Add in the top-right corner to finalize storage.

Method 2: Creating Passes via Web-Based Generators

Web-based generators enable pass creation across desktop environments, bulk payload generation, and remote pass distribution via URLs or email attachments.

Recommended Web Utilities

PassKit Cloud Platforms: Enterprise-grade platforms providing REST APIs, webhook integration, and real-time pass updates.
Passsource: Web-based form interface to input data points and download pre-compiled .pkpass bundles.
PassCreator: Visual builder with dynamic CSV batch generation and CRM connectivity.

Step-by-Step Web Workflow

Open the web interface in a desktop browser.
Select the target pass template (e.g., Generic or Store Card).
Upload source assets:
- Logo: logo.png (3x: 480x150 px, PNG with transparency).
- Icon: icon.png (3x: 87x87 px, PNG).
- Strip/Hero Image: strip.png (3x: 1125x369 px, PNG).
Configure data fields:
- Assign machine keys (e.g., member-id, balance-cents).
- Define human-readable labels (e.g., MEMBERSHIP NUMBER, REWARDS BALANCE).
- Populate corresponding field values.
Define back-of-pass metadata:
- Populate terms and conditions, contact information, website URLs, and privacy policy links into backFields. URLs and phone numbers convert to interactive links in iOS.
Compile the .pkpass file:
- Click Generate Pass. The server generates pass.json, packages image assets, computes manifest.json, signs the archive using an authorized Apple certificate, and generates a .pkpass binary.
Import into iOS:
- Direct Scan: Display the generated download URL as a desktop QR code. Scan the code using the native iPhone Camera app to open the .pkpass file directly in Mobile Safari.
- AirDrop: Transfer the downloaded .pkpass file from macOS to iPhone via AirDrop. iOS automatically triggers the pass import sheet.
- Email/Web Download: Host the .pkpass on an HTTPS web server configured with the HTTP response header Content-Type: application/vnd.apple.pkpass.

Method 3: Automating Passes with Apple Shortcuts

The iOS Shortcuts app allows programmatic creation of custom cards without third-party software installations, leveraging built-in web API requests and base64 encoders.

Building a Pass Generation Shortcut

[Physical Card Image] ──> [Extract Barcode via Shortcut Action] ──> [Format API JSON Payload] ──> [Fetch .pkpass from API] ──> [Open in Apple Wallet]

To create an automated barcode-to-Wallet shortcut:

Open the Shortcuts app on iOS and tap + to create a new workflow.
Add the Take Photo or Select Photos action to capture the physical loyalty card.
Add the Extract Barcode from Image action. Set the input to the photo result.

Add a Dictionary action to structure the pass payload:

{
  "passType": "generic",
  "organizationName": "Custom Gym",
  "description": "Gym Pass",
  "barcodeType": "PKBarcodeFormatCode128",
  "barcodeMessage": "Shortcut Result (Barcode Text)",
  "backgroundColor": "rgb(24, 24, 27)",
  "foregroundColor": "rgb(255, 255, 255)",
  "labelColor": "rgb(161, 161, 170)"
}

Add a Get Contents of URL action:
- Set the URL to a pass signing endpoint or an instance of an open-source pass builder API.
- Set the Method to POST.
- Attach the Dictionary action result to the HTTP Request Body as JSON.
Add the Get Contents of URL result output to a Set Name action. Rename the incoming file stream to MembershipCard.pkpass.
Add the Open In action and target Apple Wallet.
Save the shortcut as Add Card to Wallet.

Run the shortcut, point the camera at a barcode, and the script extracts the alphanumeric payload, generates the .pkpass via the API, and delivers the pass directly into Apple Wallet.

Method 4: The Developer Method Using PassKit and JSON

This workflow details how to manually build, sign, and compile a production-ready .pkpass package using Apple Developer tools, standard JSON specifications, and OpenSSL.

+-------------------------------------------------------------------------------+
|                         PASS COMPILATION PIPELINE                             |
+-------------------------------------------------------------------------------+
| 1. Create Workspace Directory: /pass_workspace/                               |
| 2. Write pass.json Specification                                              |
| 3. Add Retina Graphics (icon.png, logo.png)                                   |
| 4. Generate manifest.json via SHA-1 Hashing:                                  |
|    $ openssl sha1 [assets...] > manifest.json                                 |
| 5. Sign manifest.json with Apple Developer Certificate:                       |
|    $ openssl smime -sign -in manifest.json -out signature ...                 |
| 6. Bundle Assets into Final ZIP Package:                                      |
|    $ zip -r pass.pkpass manifest.json signature pass.json *.png               |
+-------------------------------------------------------------------------------+

Prerequisites

An active Apple Developer Account.
A Pass Type ID registered in the Apple Developer Portal (e.g., pass.com.example.loyalty).
A Pass Signing Certificate exported from macOS Keychain Access as a .p12 file.
The Apple Worldwide Developer Relations (WWDR) Intermediate Certificate G4.
OpenSSL installed on the local machine.

Step 1: Export Signing Certificates

Extract the private key, certificate, and WWDR certificate using OpenSSL:

# Export the pass certificate
openssl pkcs12 -in passcertificate.p12 -clcerts -nokeys -out passcert.pem

# Export the private key (decrypted)
openssl pkcs12 -in passcertificate.p12 -nocerts -nodes -out passkey.pem

# Download Apple WWDR G4 intermediate certificate
curl -O https://www.apple.com/certificateauthority/AppleWWDRCAG4.cer
openssl x509 -inform DER -in AppleWWDRCAG4.cer -out wwdr.pem

Step 2: Write `pass.json`

Create a dedicated project directory and author the pass.json file:

mkdir pass_workspace
cd pass_workspace

Save the following content as pass.json:

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.example.loyalty",
  "serialNumber": "USR-8492041",
  "teamIdentifier": "A1B2C3D4E5",
  "organizationName": "Apex Fitness",
  "description": "Apex Fitness Membership Pass",
  "foregroundColor": "rgb(255, 255, 255)",
  "backgroundColor": "rgb(15, 23, 42)",
  "labelColor": "rgb(148, 163, 184)",
  "logoText": "Apex Fitness",
  "barcodes": [
    {
      "format": "PKBarcodeFormatQR",
      "message": "https://apexfitness.example.com/user/8492041",
      "messageEncoding": "iso-8859-1",
      "altText": "8492041"
    }
  ],
  "generic": {
    "primaryFields": [
      {
        "key": "member",
        "label": "MEMBER NAME",
        "value": "Alex Mercer"
      }
    ],
    "secondaryFields": [
      {
        "key": "tier",
        "label": "MEMBERSHIP LEVEL",
        "value": "Platinum VIP"
      }
    ],
    "auxiliaryFields": [
      {
        "key": "expires",
        "label": "VALID THROUGH",
        "value": "2026-12-31T23:59:59Z",
        "dateStyle": "PKDateStyleShort"
      }
    ],
    "backFields": [
      {
        "key": "supportPhone",
        "label": "Customer Support",
        "value": "+1 (800) 555-0199"
      },
      {
        "key": "terms",
        "label": "Terms & Conditions",
        "value": "Passes are non-transferable. Present at front reception upon facility entry."
      }
    ]
  }
}

Step 3: Populate Graphics

Place required image assets directly in pass_workspace/:

icon.png (29x29 px) and icon@2x.png (58x58 px)
logo.png (160x50 px) and logo@2x.png (320x100 px)

Step 4: Generate `manifest.json`

Calculate SHA-1 checksums for all files in the directory and format as a JSON object:

python3 -c "
import os, hashlib, json

manifest = {}
for filename in os.listdir('.'):
    if filename not in ['manifest.json', 'signature', '.DS_Store'] and not filename.startswith('.'):
        with open(filename, 'rb') as f:
            manifest[filename] = hashlib.sha1(f.read()).hexdigest()

with open('manifest.json', 'w') as f:
    json.dump(manifest, f, indent=2)
"

Step 5: Sign the Manifest

Sign manifest.json using the Pass Type ID certificate, private key, and Apple WWDR certificate using OpenSSL:

openssl smime -binary -sign \
  -in manifest.json \
  -out signature \
  -outform DER \
  -signer passcert.pem \
  -inkey passkey.pem \
  -certfile wwdr.pem

Step 6: Package the `.pkpass` Archive

Bundle the components into a compressed archive with the .pkpass file extension:

zip -q -r ApexGym.pkpass manifest.json signature pass.json *.png

Verify that ApexGym.pkpass contains all files at the root directory level without subdirectories. Double-click the file on macOS or AirDrop it to an iPhone to trigger native ingestion into Apple Wallet.

Advanced Pass Features

Custom passes support dynamic updates and lock screen interactions via geolocation arrays, timestamps, and Apple Push Notification service (APNs) integration.

+-------------------------------------------------------------------------+
|                       RELEVANCE & UPDATE PIPELINE                       |
+-------------------------------------------------------------------------+
| [GPS Coordinates Detected]    --> Auto-Surface Pass on Lock Screen      |
| [relevantDate Reached]        --> Lock Screen Alert / Shortcut Card     |
| [Server Post to APNs Push]    --> Triggers Device PassKit Update        |
| [Device Calls REST Endpoint]  --> Returns Updated pass.json Payload     |
+-------------------------------------------------------------------------+

Lock Screen Relevance Triggers

Passes automatically display notifications on the lock screen based on proximity and timing.

Geolocation Triggers

Include a locations array inside pass.json containing up to ten latitude and longitude coordinates:

"locations": [
  {
    "latitude": 37.774929,
    "longitude": -122.419416,
    "relevantText": "Welcome to Apex Fitness Market Street. Tap to display barcode."
  },
  {
    "latitude": 37.789172,
    "longitude": -122.401449,
    "relevantText": "Welcome to Apex Fitness Financial District."
  }
]

When the device enters within 100 meters of these coordinates, iOS surfaces the relevant pass directly on the lock screen.

Date and Time Triggers

For event tickets, boarding passes, and time-restricted passes, define the relevantDate key using W3C ISO-8601 formatting:

"relevantDate": "2025-06-15T18:30:00Z"

iOS displays the pass on the lock screen prior to the scheduled timestamp and removes the foreground notification once the window expires.

Push Notifications and Dynamic Updates

Apple Wallet supports remote content updates without requiring the user to re-download the .pkpass file.

To configure remote pass updates:

Define Web Service Keys: Add webServiceURL and authenticationToken to pass.json:

"webServiceURL": "https://api.example.com/passes/",
"authenticationToken": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"

Registration Endpoint: When the pass is installed, iOS sends an HTTPS POST request to:
```
POST https://api.example.com/passes/v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}
```
The payload contains the device pushToken. Store this token in your database.
Triggering an Update: When an account balance or gate changes on the backend:
- Send an empty APNs push notification to the registered pushToken using the Pass Type ID topic.
Delivering New Payload:
- The device receives the push notification and queries the backend:
```
GET https://api.example.com/passes/v1/passes/{passTypeIdentifier}/{serialNumber}
```
- The server compiles, signs, and returns an updated .pkpass package.
Change Notifications: If a specific field changed, mark the field with changeMessage in pass.json:
```
{
  "key": "balance",
  "label": "REWARDS POINTS",
  "value": "4,250",
  "changeMessage": "Your rewards balance updated to %@ points."
}
```
iOS updates the pass face and triggers a lock screen notification displaying the formatted string.

Frequently Asked Questions (FAQ)

Can I add a custom pass to Apple Wallet without an Apple Developer account?

Yes. Third-party iOS applications (such as Pass2U Wallet or Pass4Wallet) and web pass generators handle pass generation and cryptographic signing using their own pre-configured developer certificates. An Apple Developer account is only required when building passes from scratch via command-line tools, hosting private APIs, or customizing enterprise Pass Type IDs.

Which barcode formats does Apple Wallet support?

Apple Wallet natively supports four barcode formats defined under PKBarcodeFormat:

PKBarcodeFormatQR: Standard 2D QR Code.
PKBarcodeFormatAztec: 2D Aztec Code.
PKBarcodeFormatPDF417: 2D stacked barcode used for transport and boarding tickets.
PKBarcodeFormatCode128: 1D continuous linear barcode.

Legacy 1D formats such as UPC-A, EAN-13, and Code 39 are not supported by the Wallet rendering engine. To store these cards, convert the payload into a 2D QR Code or Code 128 format, or store the numeric value in the altText field for manual scanning.

Can I share custom passes with other iPhone users?

Yes. Open the pass in the Apple Wallet app, tap the More button (three dots) in the top-right corner, select Pass Details, and tap the Share sheet icon. You can transmit the underlying .pkpass file via AirDrop, Messages, Mail, or an iCloud link.

Why is my custom pass not showing on the lock screen automatically?

Ensure the following settings are active:

Open Settings > Privacy & Security > Location Services on your iPhone. Set Wallet to While Using the App.
Open Settings > Wallet & Apple Pay and verify that Double-Click Side Button is enabled.
Verify that the pass.json file contains valid, high-precision latitude/longitude coordinates or an active relevantDate formatted according to ISO-8601.
Open the pass in Apple Wallet, tap the More button, select Pass Details, and ensure Suggest on Lock Screen is enabled.

Can I use custom passes on Apple Watch?

Yes. Passes added to an iPhone Wallet automatically synchronize to the paired Apple Watch. To verify synchronization:

Open the Watch app on the paired iPhone.
Select the My Watch tab.
Tap Wallet & Apple Pay.
Set the configuration to Mirror my iPhone. The custom pass will appear in the Apple Watch Wallet app and display readable 2D/1D barcodes on the OLED screen.

0 views