Two Very Different Uses of "NFC" in Wallet Passes
Important: Before scoping contactless checkout or access control with stakeholders, distinguish NDEF NFC Tag Distribution (open-standard URL tags that work with any smartphone out of the box) from Encrypted Tap-to-Redeem (Apple VAS and Google Smart Tap, which transmit an encrypted pass payload from the wallet to a specialized NFC reader terminal).
| Capability | Purpose | Protocol & Model | Hardware & Approval Needed |
|---|---|---|---|
| NDEF NFC Tag Distribution | Customer taps unlocked phone on counter sticker -> opens Add to Wallet or PassFlow URL | ISO/IEC 14443 NDEF URI Record | Inexpensive NTAG213/215 sticker only; no reader hardware or Apple VAS needed. |
| Tap-to-Redeem (Apple VAS / Google Smart Tap) | Customer holds phone/Watch near terminal -> reader decrypts pass payload (message) | Apple VAS & Google Smart Tap (NFC model & Template.nfc) | Requires VAS/Smart Tap NFC reader hardware + merchant public/private key configuration (not enabled by default on every account). |
Pass NFC Model & pass.json nfc Dictionary Architecture
When contactless redemption is enabled on a template (Template.nfc / Passinstance database NFC model), Passinstance embeds cryptographic contactless metadata into both the Apple Wallet pass.json nfc dictionary and the Google Wallet object's smartTapRedemptionValue:
NFC Configuration Properties & Constraints
Property (NFC / Template.nfc) | Apple pass.json Key | Type & Constraint | Technical Behavior |
|---|---|---|---|
message | nfc.message | string (Max 64 bytes UTF-8) | The cleartext payload encrypted by the device and transmitted to the NFC reader (defaults to the pass serialNumber or externalId). |
encryptionPublicKey | nfc.encryptionPublicKey | string (Base64 DER/PEM) | Compressed or uncompressed ECDH P-256 (prime256v1) public key matching the private key loaded onto your NFC reader terminals. |
nfcFaceIdRequired | nfc.requiresAuthentication | boolean | When true, iOS requires the passholder to authenticate via Face ID, Touch ID, or Passcode before transmitting the VAS payload. |
nfcNoBarcode | Omits barcodes[] | boolean | When true, suppresses the visual 2D QR/Aztec barcode on the pass front so the pass can only be presented via encrypted NFC tap. |
Example: Apple Wallet pass.json nfc Dictionary & Template Config
When nfcEnabled: true is configured on a template, Passinstance serializes the nfc dictionary at the root of pass.json:
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.phenixroasters.access",
"serialNumber": "PI-8849-2026-X9",
"nfc": {
"message": "PI-8849-2026-X9",
"encryptionPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8v3x9K2m5N7p1Q4r6S8t0V2w4Y6z8A1b3C5d7E9f0G2h4J6k8L0m2N4p6Q8r0S==",
"requiresAuthentication": true
}
}
To update a template's NFC settings via the REST API, patch the template resource (and verify configuration with POST /api/v1/nfc/test):
PATCH /api/v1/templates/7b9e4c12-3f81-4a90-b8d2-19c48a70e112
{
"nfc": {
"message": "{serialNumber}",
"encryptionPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8v3x9K2m5N7p1Q4r6S8t0V2w4Y6z8A1b3C5d7E9f0G2h4J6k8L0m2N4p6Q8r0S==",
"requiresAuthentication": true
},
"nfcFaceIdRequired": true,
"nfcNoBarcode": false
}
Best Practice: Keep Optical 2D Barcode Fallback Enabled
Unless you are deploying high-security employee access badges where visual barcode screenshots must be strictly prevented (nfcNoBarcode: true or addSecurityAnimation: true), keep nfcNoBarcode: false so passes render a backup 2D QR or Aztec barcode. This ensures staff can still validate passes with optical cameras if a terminal is offline or a customer's phone NFC antenna is disabled.
Review NFC Wallet Passes Scope, Apple VAS, Google Smart Tap, and Compatible NFC Readers.
