Documentation

Everything you need to know about creating, signing, and distributing Apple Wallet passes with PassMaker.

This page is the quick reference. Each section links to a longer field guide that covers the same ground in depth, with worked examples and failure modes.

Pass Structure

An Apple Wallet pass is a compressed ZIP archive (renamed to .pkpass) containing a JSON description, image assets, and a digital signature.

1pass.json

The core file defining the pass type, structure, content, and visual appearance.

2manifest.json

A JSON file containing SHA1 checksums for every file in the pass package.

3signature

A detached PKCS#7 digital signature of the manifest file, verifying the issuer's identity.

4Images

Standard assets like icon.png, logo.png, and strip.png (plus @2x and @3x variants).

Full guide: PKPass manifest and package structure

Pass Types

Apple Wallet supports five distinct pass styles, each designed for a specific use case.

✈️

Boarding Pass

For flights, trains, and other transit. Displays origin, destination, and boarding information prominently.

🎟️

Event Ticket

For concerts, movies, and sporting events. Highlights the event name, venue, and seat details.

✂️

Coupon

For discounts and special offers. Focuses on the offer value and expiration date.

💳

Store Card

For loyalty programs and gift cards. Displays current balance or points.

🎫

Generic

For anything that doesn't fit the other categories, like gym memberships or coat check tickets.

Full guide: How to create an Apple Wallet pass

Fields & Data

Passes display information using three main field types, each with a specific visual priority.

pass.json

{
  "boardingPass": {
    "primaryFields": [
      {
        "key": "origin",
        "label": "SAN FRANCISCO",
        "value": "SFO"
      }
    ],
    "secondaryFields": [
      {
        "key": "gate",
        "label": "GATE",
        "value": "A12"
      }
    ],
    "auxiliaryFields": [
      {
        "key": "seat",
        "label": "SEAT",
        "value": "4A"
      }
    ]
  }
}

Primary Fields

The most important information, displayed prominently at the top (e.g., Flight Number, Balance).

Secondary Fields

Supporting details, usually displayed in rows below the primary fields.

Auxiliary Fields

Additional info, often displayed in the last row or on the back of the pass.

Full guide: pass.json reference with working examples

Validation

To ensure your pass works correctly in Apple Wallet, validate pass.json on its own while authoring, then upload the finished package to our Validator tool for manifest, signature, certificate, identity, and archive checks.

Required Keys: passTypeIdentifier, teamIdentifier, serialNumber, etc.
Valid JSON: The pass.json file must be valid JSON with no syntax errors.
Package Contents: A complete .pkpass package should include manifest.json, signature, and required image assets.
Signature Verification: Complete .pkpass uploads are checked for manifest hashes, PKCS#7 integrity, certificate dates, the embedded WWDR chain, Team ID, and Pass Type ID.

Full guide: How to sign a .pkpass file correctly

Troubleshooting: “Safari cannot download this file”

Validator FAQ

Can I validate only pass.json?

Yes. A JSON-only validation checks the fields Apple Wallet expects in pass.json without marking missing package files as errors.

What files are required in a .pkpass?

At minimum, a distributable pass package needs pass.json, manifest.json, signature, and required image assets such as icons.

Does the web validator verify signing?

Yes. For complete packages, it verifies manifest hashes, the detached PKCS#7 signature, certificate dates, the WWDR chain, and signer identity. You should still install the exact production download on a physical device before shipping.

Create Apple Wallet passes faster

If you do not want to hand-write pass.json, PassMaker helps you create Apple Wallet passes on iPhone and then validate the output here.

Download on the App Store