.pkpass format: what is inside an Apple Wallet pass file

What a .pkpass file is: a signed zip with pass.json, manifest.json, a signature and images. How the files fit together and how to validate one.

Last updated 2026-11-05

A .pkpass file is the package Apple Wallet installs. It is a zip archive with the extension .pkpass and the MIME type application/vnd.apple.pkpass. Inside are the pass description, the images, a manifest of file hashes and a signature that proves who issued the pass. Apple documents the format in its Wallet Developer Guide and the Wallet Passes reference.

Google Wallet does not use .pkpass files. Google passes are created through the Google Wallet API and added with a save link. This page covers Apple Wallet only.

The files in a pass package

File	Purpose
`pass.json`	Required. Describes the pass: identifiers, the pass style, the fields shown, barcodes and colours.
`manifest.json`	Required. A JSON object that maps each file name in the package to its SHA-1 hash.
`signature`	Required. A detached signature of `manifest.json`, made with the Pass Type ID certificate and chained to Apple's intermediate certificate.
`icon.png`	Required. Shown on the lock screen and in notifications. Higher-resolution `icon@2x.png` and `icon@3x.png` are supplied for denser screens.
`logo.png`, `strip.png`, `thumbnail.png`, `background.png`, `footer.png`	Optional images, depending on the pass style. The names are fixed, with `@2x` and `@3x` variants.
`<language>.lproj/`	Optional folders with translated `pass.strings` and localised images.

pass.json

pass.json must be valid JSON. The required keys are formatVersion (always 1), passTypeIdentifier, serialNumber, teamIdentifier, organizationName and description. The pass also has exactly one style key that holds its fields: boardingPass, coupon, eventTicket, generic or storeCard.

A minimal pass.json

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.example.membership",
  "serialNumber": "0412",
  "teamIdentifier": "ABCDE12345",
  "organizationName": "Riverside Club",
  "description": "Riverside Club membership card",
  "barcodes": [
    { "format": "PKBarcodeFormatQR", "message": "0412", "messageEncoding": "iso-8859-1" }
  ],
  "storeCard": {
    "primaryFields": [{ "key": "member", "label": "Member", "value": "Alex Morgan" }]
  }
}

Barcodes use the formats PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec and PKBarcodeFormatCode128. A pass that can be updated also sets webServiceURL and an authenticationToken of at least 16 characters, which Wallet uses to ask your server for new versions.

manifest.json and the signature

The manifest lists every other file in the package with its SHA-1 hash. The signature is made over the manifest, so changing any file invalidates the pass. Wallet refuses to add a package if a hash does not match, a file is missing from the manifest or the signature does not verify.

manifest.json (example hashes)

{
  "pass.json": "3f786850e387550fdab836ed7e6dc881de23001b",
  "icon.png": "89e6f2c0f7a3b3c1e0b9d7f5a4a3c2b1d0e9f8a7",
  "icon@2x.png": "2b1d0e9f8a789e6f2c0f7a3b3c1e0b9d7f5a4a3c"
}

How to validate a .pkpass file

Open the free pkpass validator. It runs in your browser and checks that the zip contains pass.json, manifest.json and signature, that the required keys and one style are present, that barcode formats are valid and that every hash in the manifest matches. Nothing is uploaded.
List the contents yourself with unzip -l pass.pkpass, and unzip it to read pass.json.
Check a hash by hand with shasum -a 1 icon.png and compare it with the manifest.
Test on a real iPhone. The validator cannot verify the signature chain, so the device is the final check.

Common reasons a pass will not add

A file in the package is missing from manifest.json, or its hash is out of date after an edit.
icon.png is missing or is not a valid PNG.
The pass has no style key, or more than one.
webServiceURL is set without an authenticationToken.
The signing certificate has expired, or it does not match passTypeIdentifier and teamIdentifier.

Do you need to build this yourself?

Not on Shakewell. Shakewell builds, signs and renews the package for you, and gives you an install link that adds the pass to Apple Wallet or Google Wallet depending on the phone. See Apple Wallet setup for what Shakewell handles, and the passes API to create a pass from code. If a pass does not add, start with troubleshooting.