nfcpasses

How to read an Apple Wallet NFC pass

Apple Wallet gives people a convenient way to organize and use rewards cards, boarding passes, tickets, and gift cards in one place, and Apple Pay and Apple Wallet make it simple to enroll, reward, and engage customers on their iPhone or Apple Watch. To read Apple Wallet NFC pass data at your counter, you need three things: an NFC-enabled pass, a short message and public key inside that pass, and a compatible NFC pass reader (often called a VAS reader). The steps below cover each, including how PassNinja can issue and sign the passes for you.

With contactless passes, customers simply hold their iPhone to the NFC reader, waking the device and instantly pulling up the relevant pass from Apple Wallet. An Apple Wallet NFC loyalty card, event ticket, or membership pass uses that tap to pass its NFC payload from the device to an Apple Pay terminal.

Barcode passes vs. NFC-enabled Wallet passes

A Wallet pass can carry a message or payload to display as a barcode.

An NFC-enabled pass adds a contactless tap. Inside the pass file, Apple's nfc dictionary represents the near-field communication (NFC) payload the device passes to an Apple Pay terminal. That dictionary also includes an encryptionPublicKey field for the public encryption key the Value Added Services protocol uses—you either put your own public key into pass.json and store the private key in your NFC / VAS reader, or use the S550 PassNinja sets up for you when you order it with pass templates in your account (Step 2). See Apple VAS and ECP explained.

What a business needs to read an Apple Wallet NFC pass

Setting up an Apple Wallet NFC loyalty or membership flow follows three steps:

Step 1: Get your NFC passes through PassNinja (or apply to Apple yourself)

Adding NFC to an Apple Wallet pass requires a special entitlement issued by Apple, and Apple is selective about which businesses it approves.

PassNinja is the straightforward way around that bottleneck: its software and APIs create, issue, update, and revoke passes for Apple Wallet and Google Wallet. On the Apple side, PassNinja signs your NFC passes itself under its own Apple entitlement, eliminating Apple's lengthy approval process.

If you prefer to hold your own entitlement, apply to Apple at developer.apple.com/contact/passkit and sign passes with your own Apple Value Added Services (Apple VAS) certificate; obtaining your own NFC entitlement and the Apple VAS survey typically run several weeks and are paced by Apple (see An NFC loyalty card for your café).

Step 2: Configure the pass message and encryption key

Apple's Pass.NFC dictionary uses three fields:

  1. message: The payload transmitted to the Apple Pay terminal, of no more than 64 bytes (the system truncates longer messages).
  2. encryptionPublicKey: The public encryption key the Value Added Services protocol uses. In a self-managed setup, you put this public key into pass.json and store the matching private key in your NFC / VAS reader. Alternatively, when you order a Socket Mobile S550 from PassNinja and have existing pass templates created in your account, PassNinja pre-configures that reader with the credentials that allow the reader to work out of the box with your passes.
  3. requiresAuthentication: An optional Boolean (valid in iOS 13.1 and later, defaulting to false) indicating whether the NFC pass requires user authentication for each use.

Step 3: Connect a VAS reader and read the customer's tap

Store payment terminals must already accept Apple Pay and be certified for VAS (and for Android users, Google's Smart Tap requires an NFC terminal compatible with the Smart Tap protocol—see Google Smart Tap vs Apple VAS). Readers such as the ID TECH VP3300 and VP8300 support Apple VAS and Google SmartTap 2.1 alongside traditional EMV payments. You can also choose from PassNinja's list of NFC reading hardware that works with PassNinja-issued passes—including ID TECH's Kiosk V (the VP3300 isn't on that list) and the S550 PassNinja sets up for you when you order it with pass templates in your account.

When a customer holds their iPhone to the reader, it wakes the device and pulls up the pass; with their iPhone unlocked or via Face ID, Touch ID, or double-clicking the side button on Apple Watch, they check in and the device passes the NFC payload to the terminal.

How the nfcpasses.com browser demo works

The nfcpasses.com demo reads Apple Wallet passes with an ID TECH VP3300 connected to desktop Chrome or Edge. It uses WebHID, which Chrome describes as a way to implement device-specific logic in JavaScript: the page asks you to choose the reader the first time, and can reuse it after that. Chrome has supported WebHID since version 89, Edge and Opera follow Chrome, and Firefox, Safari and Chrome on Android don't support it.

The demo is tested with the VP3300 USB on firmware NEO 1.01.182. It asks before adding its three demo passes (a coffee card, an event ticket and a membership) to empty slots on the reader, then shows each pass's message when you tap your phone. See VP3300 WebHID setup.

Frequently asked questions

Why won't Apple Wallet open my NFC pass?

Adding NFC to a pass requires a special entitlement issued by Apple, and a pass containing an NFC payload must be signed with an Apple Value Added Services (Apple VAS) certificate to be ingested into Wallet. If you don't hold your own Apple entitlement, issue the pass through PassNinja, which signs Apple Wallet NFC passes under its own.

How much data can an Apple Wallet NFC pass send on a tap?

The message payload inside Pass.NFC can be no more than 64 bytes; the system truncates messages longer than 64 bytes.

Do I need my own Apple NFC entitlement?

No. PassNinja issues and signs Apple Wallet NFC passes under its own entitlement, so there's nothing to apply for; it signs the passes itself and never gives you a certificate to sign with. If you'd rather hold your own entitlement, you can apply to Apple at developer.apple.com/contact/passkit.

Sources