Skip to content
Guida del Centro assistenza · NFC e contactlessFase di onboarding 2
3 min di letturaVerificato 2026-11-16

Configurazione NFC dei pass

Distingui i tag NDEF aperti (apertura link Wallet) dal riscatto crittografato su terminali NFC compatibili.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito
Elementi chiave dell'interfaccia

Configurazione codice a barre, QR code e NFC (Zoom)

Configura il formato QR-Code, l'origine del valore, il payload dinamico ({memberQrToken}), il testo alternativo ({passReference}) e l'NFC.

Due utilizzi molto diversi della tecnologia "NFC" nei pass Wallet

Importante: Prima di progettare flussi di cassa contactless o controllo accessi con gli stakeholder, occorre distinguere tra Distribuzione tramite tag NFC NDEF (tag URL a standard aperto che funzionano subito su qualsiasi smartphone) e Tap-to-Redeem cifrato (Apple VAS e Google Smart Tap, che trasmettono un payload cifrato del pass dal Wallet a un lettore NFC dedicato).

FunzionalitàScopoProtocollo e modelloHardware e approvazioni richiesti
Distribuzione tag NFC NDEFIl cliente avvicina il telefono sbloccato allo sticker da banco -> apre URL Aggiungi al Wallet o PassFlowRecord URI NDEF ISO/IEC 14443Solo un economico sticker NTAG213/215; nessun lettore hardware né Apple VAS necessario.
Tap-to-Redeem (Apple VAS / Google Smart Tap)Il cliente avvicina telefono/Watch al terminale -> il lettore decifra il payload del pass (message)Apple VAS e Google Smart Tap (modello NFC e Template.nfc)Richiede lettori hardware NFC VAS/Smart Tap + configurazione chiavi pubbliche/private merchant (non attiva per default su tutti gli account).

Architettura del modello NFC e del dizionario nfc in pass.json

Quando il riscatto contactless è abilitato su un modello (Template.nfc / modello Passinstance database NFC), Passinstance integra i metadati crittografici contactless sia nel dizionario nfc di pass.json su Apple Wallet sia in smartTapRedemptionValue sull'oggetto Google Wallet:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PAYLOAD PASS NFC CIFRATO E HANDSHAKE TERMINALE
FASE 01 SCHEMA NFC MODELLO E PASS (Modello NFC)
nfcEnabled: true
message: Payload dinamico (fino a 64 byte, es. serialNumber o token)
encryptionPublicKey: Chiave pubblica Base64 ECDH P-256 (prime256v1)
requiresAuthentication (nfcFaceIdRequired): Impone Face ID / Touch ID
nfcNoBarcode: Soppressione opzionale del barcode 2D sul fronte della tessera
pass.json Apple Wallet
FASE 02A "nfc": {
"message": "PI-8849-2026-X9", "encryptionPublicKey": "MDkwEw...", "requiresAuthentication": true }
[ Campo RF 13.56
TERMINALE LETTORE POS / ACC
1
Trasmette hash Apple VAS Pass Type ID
2
Esegue accordo chiavi effimero ECDH P
3
Inoltra message decifrato a `POST /
WalletObject Google Wallet
FASE 02B "smartTapRedemptionValue": "<msg>"
"hasUsers": true
Collegato a redemptionIssuers (collectorId / chiave ECDH P-256)
ISO/IEC 14443 ]
I (NFC / Verifone / Ingenico)
Collector ID Google Smart Tap
6 e decifratura AES-GCM
/v1/scanso/api/v1/reader/redeem`

Proprietà e vincoli di configurazione NFC

Proprietà (NFC / Template.nfc)Chiave Apple pass.jsonTipo e vincoloComportamento tecnico
messagenfc.messagestring (Max 64 byte UTF-8)Il payload in chiaro cifrato dal dispositivo e trasmesso al lettore NFC (predefinito: serialNumber o externalId del pass).
encryptionPublicKeynfc.encryptionPublicKeystring (Base64 DER/PEM)Chiave pubblica ECDH P-256 (prime256v1) compressa o non compressa corrispondente alla chiave privata caricata sui lettori NFC.
nfcFaceIdRequirednfc.requiresAuthenticationbooleanQuando true, iOS richiede al titolare l'autenticazione tramite Face ID, Touch ID o codice prima di trasmettere il payload VAS.
nfcNoBarcodeOmette barcodes[]booleanQuando true, nasconde il codice a barre ottico 2D QR/Aztec sul fronte affinché il pass possa essere presentato solo tramite tap NFC cifrato.

Esempio: dizionario nfc in pass.json Apple Wallet e configurazione modello

Quando nfcEnabled: true è attivo su un modello, Passinstance serializza il dizionario nfc alla radice di pass.json:

JSON
{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.phenixroasters.access",
  "serialNumber": "PI-8849-2026-X9",
  "nfc": {
    "message": "PI-8849-2026-X9",
    "encryptionPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8v3x9K2m5N7p1Q4r6S8t0V2w4Y6z8A1b3C5d7E9f0G2h4J6k8L0m2N4p6Q8r0S==",
    "requiresAuthentication": true
  }
}

Per aggiornare le impostazioni NFC di un modello tramite REST API, invii una patch sulla risorsa template (e verifichi la configurazione con POST /api/v1/nfc/test):

JSON
PATCH /api/v1/templates/7b9e4c12-3f81-4a90-b8d2-19c48a70e112
{
  "nfc": {
    "message": "{serialNumber}",
    "encryptionPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8v3x9K2m5N7p1Q4r6S8t0V2w4Y6z8A1b3C5d7E9f0G2h4J6k8L0m2N4p6Q8r0S==",
    "requiresAuthentication": true
  },
  "nfcFaceIdRequired": true,
  "nfcNoBarcode": false
}

Best practice: mantenere attivo il codice a barre ottico 2D di riserva

A meno che non si stiano distribuendo badge di accesso aziendali ad alta sicurezza in cui gli screenshot dei codici a barre devono essere rigorosamente impediti (nfcNoBarcode: true oppure addSecurityAnimation: true), mantenga nfcNoBarcode: false affinché i pass mostrino un codice a barre 2D QR o Aztec di backup. Ciò garantisce che lo staff possa comunque validare i pass con fotocamere ottiche se un terminale è offline o se l'antenna NFC sullo smartphone del cliente è disattivata.

Consulti Ambito NFC Wallet Passes, Apple VAS, Google Smart Tap e Lettori NFC compatibili.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.