Barcodes

Apple Wallet barcode formats and compatibility

Choose between QR, PDF417, Aztec, and Code 128, set message encodings, and design barcodes that scan reliably from an iPhone display.

By Swapnanil DholUpdated August 13, 20268 min read

What you’ll leave with

Choose a format supported by the real scanners in your deployment—not only by Wallet.
Keep messages compact and provide altText for manual recovery.
Test screen scanning at realistic brightness, distance, and device sizes.

Choose the format for the scanner environment

QR and Aztec are two-dimensional formats that fit useful payloads into a square footprint. PDF417 is common in transport and identity workflows and can carry more data in a wide shape. Code 128, Code 39, Codabar, EAN-13, and Interleaved 2 of 5 are linear formats suited to specific retail, inventory, library, and legacy scanner environments.

The best format is the one already supported by the gate, point-of-sale terminal, or handheld scanner. Ask the operator for accepted symbologies and maximum payload length before building the pass.

QR: broadly recognized and a strong general-purpose fallback
Aztec: compact 2D symbol commonly used in ticketing
PDF417: wide 2D symbol used in travel and credential workflows
Code 128 and Code 39: linear formats for alphanumeric identifiers
EAN-13: fixed-length retail product identifiers
Codabar and I2of5: legacy linear formats used by specific scanners

Author barcodes without losing compatibility

Use the barcodes array so you can offer formats in preference order. In iOS 27 and later, Wallet can use newer linear formats while an earlier compatible entry such as QR acts as the fallback for older systems. Each entry includes format, message, and messageEncoding. Add altText when a human-readable code helps staff recover from scanning problems.

Keep a legacy barcode dictionary only when you intentionally support older consumers. Ensure the legacy and modern messages represent the same credential to prevent confusing behavior across OS versions.

"barcodes": [
  {
    "format": "PKBarcodeFormatAztec",
    "message": "TICKET:2026:0088",
    "messageEncoding": "iso-8859-1",
    "altText": "2026-0088"
  },
  {
    "format": "PKBarcodeFormatQR",
    "message": "TICKET:2026:0088",
    "messageEncoding": "iso-8859-1",
    "altText": "2026-0088"
  }
]

Design a compact and secure payload

Longer messages create denser symbols that are harder to scan from small or damaged screens. Prefer an opaque identifier or signed compact token over a full record. Avoid placing personal information in the barcode unless the operational need and privacy model justify it.

If the credential can be revoked or updated, the scanner should resolve the identifier against authoritative state. A visually updated pass does not automatically invalidate a copied barcode unless the backend enforces that policy.

Test the complete scanning path

Test on the oldest and smallest supported iPhone, at low and high brightness, with screen protectors, and under the lighting found at the venue. Include the actual scanner firmware and network conditions. A barcode that scans from a desktop monitor is not sufficient evidence.

Record fallback procedures for offline or damaged scanners. altText, a short lookup code, and trained staff can keep admission moving when optics or connectivity fail.

Put it into practice

Build the JSON, then verify the package.

Use the free browser tools to turn the rules in this guide into a clean starting file and an actionable validation report.

Open JSON Builder Open PKPass Validator

Skip the hand-assembly.

PassMaker does every step on this page on your iPhone — field editor, artwork, manifest, PKCS#7 signing and Add to Wallet — without wiring up a signing environment.

Download on the App Store