.pkpass: the format, defined.
A .pkpass is the file format of an Apple Wallet pass: a zip archive holding pass.json, the pass images, a manifest.json of SHA-1 hashes and a detached PKCS #7 signature over that manifest. It is served with the MIME type application/vnd.apple.pkpass, and a bundle of several passes is a .pkpasses file.
Make your free cardA free Apple Wallet business card, in about a minute
HTTP/2 200
content-type: application/vnd.apple.pkpass
content-disposition: attachment; filename="yourname.pkpass"- MIME type
application/vnd.apple.pkpass. “Mail and Safari expect passes to use” it, says Apple’s guide.- Several passes
- A
.pkpassesbundle, served asapplication/vnd.apple.pkpasses. - Opening one you were sent
- That is a different question, answered on what a .pkpass file is, and how to open one.
Four steps from folder to pass.
Apple’s own build steps, in order. Skip one and Wallet refuses the file.
| Step | What happens | If it goes wrong |
|---|---|---|
| 1. Hash | Write manifest.json: a SHA-1 hash of every file in the pass | A file changed after hashing no longer matches |
| 2. Sign | Create a PKCS #7 detached signature of the manifest with the pass type certificate’s private key, saved as signature |
An expired or wrong certificate means no new adds |
| 3. Zip | Zip the folder | A stray .DS_Store zipped in but not in the manifest breaks it |
| 4. Rename | Change the extension from .zip to .pkpass |
Served as a zip, iOS will not offer to add it |
From Apple’s “Building a Pass”, read October 29, 2026.
The header that makes it open in Wallet.
A pass sent with the wrong type downloads as a mystery file. These are the headers Cardr’s server sends with a card’s pass, with the holder’s address in the file name.
HTTP/2 200
content-type: application/vnd.apple.pkpass
content-disposition: attachment; filename="yourname.pkpass"The keys every pass carries.
Inside, pass.json names the pass: formatVersion (which, in Apple’s words, “needs to be 1”), the passTypeIdentifier and teamIdentifier that must match the signing certificate, a serialNumber, the style key with its fields, and optionally barcodes and the webServiceURL that lets the pass update. Every key, with its limits, is in our pass.json reference.
{1 "formatVersion": 1,2 "passTypeIdentifier": "pass.com.example.card", "teamIdentifier": "TEAMID1234", "serialNumber": "c_example",3 "webServiceURL": "https://cardr.co",4 "storeCard": { "secondaryFields": …, "backFields": … },5 "barcodes": [ { "format": "PKBarcodeFormatQR", … } ]}- formatVersion always 1
- Identifiers match the certificate
- webServiceURL where updates come from
- storeCard style and fields
- barcodes the QR code
pass.jsonicon.pngicon@2x.pngicon@3x.pnglogo.pnglogo@2x.pnglogo@3x.pngstrip.pngstrip@2x.pngstrip@3x.png
Each image at 1x, 2x, 3x
manifest.jsonsignature
Hashes, then a signature
Where these facts come from.
Primary documents only: the standard, the platform’s own documentation or the chip maker’s datasheet. Each was read on October 29, 2026.
- Apple Developer: Building a Pass: the manifest of SHA-1 hashes, the PKCS #7 detached signature, and renaming the .zip to .pkpass
developer.apple.com/documentation/walletpasses/building-a-passRead October 29, 2026 - Apple Wallet Developer Guide: Distributing Passes: “Mail and Safari expect passes to use the application/vnd.apple.pkpass MIME type.”
developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/DistributingPasses.htmlRead October 29, 2026 - Apple Developer: Distributing and Updating a Pass: passes by web page, email or the Add to Apple Wallet button; bundles as .pkpasses, type application/vnd.apple.pkpasses
developer.apple.com/documentation/walletpasses/distributing-and-updating-a-passRead October 29, 2026 - Apple Developer: Pass: the five styles (boardingPass, coupon, eventTicket, generic, storeCard), formatVersion 1, and webServiceURL for updates
developer.apple.com/documentation/walletpasses/passRead October 29, 2026
Common questions.
What is the MIME type for a .pkpass file?
application/vnd.apple.pkpass for one pass, and application/vnd.apple.pkpasses for a bundle of several. Apple’s guide says Mail and Safari expect it.
Is a .pkpass file just a zip?
Yes, a zip with a fixed layout and a signature. Rename it to .zip and any archive tool opens it; nothing inside is encrypted.
What is the difference between .pkpass and .pkpasses?
A .pkpass is one pass. A .pkpasses is a zip of several .pkpass files, so a family’s boarding passes can be added in one go.
Why does Wallet say a pass is invalid?
Usually the manifest no longer matches the files, or the signature was made with the wrong or an expired certificate. The .pkpass viewer checks both.
Skip the certificates.
Cardr signs, serves and updates your business card pass for you, with the right type on every download. Free forever.