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

Lettori NFC compatibili

Configura terminali NFC contactless supportati per luogo di validazione dalle impostazioni NFC.

In questa guida

Panoramica: selezione e abbinamento dell'hardware lettore contactless

Poiché gli smartphone consumer iOS e Android limitano l'emulazione raw host-card e richiedono handshake crittografici con il terminale per i pass Wallet a circuito chiuso, un vero tap-to-redeem richiede hardware lettore Apple VAS + Google Smart Tap. Passinstance modella e autentica nativamente il parco lettori fisici attraverso le entità database hardware reader, reader device, store location e POS terminal.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
INTEGRAZIONE LETTORE HARDWARE NFC E TERMINALE POS
FASE 01 TAP DISPOSITIVO CLIENTE (iPhone / Watch / Android)
Campo RF 13,56 MHz ISO/IEC 14443Apple VAS / Google Smart Tap
FASE 02 LIVELLO HARDWARE LETTORE NFC FISICO
certified NFC50 / NFC Terminal (USB Keyboard Wedge, COM virtuale o Cloud HTTP)
Pin Pad POS Enterprise (Verifone P400/V400m, Ingenico Lane/Move, Square)
Decifra payload VAS / Smart Tap nel Secure Element hardware (slot 1..6)
Mod. A: Push HTTP Cloud
FASE 03A `POST/api/v1/
integrations/hardware/ reader/validate`
Wi-Fi / Ethernet diretto
Mod. B: API Gateway POS
FASE 03B `POST/api/v1/reader/
redeem`
Header: `X-Reader-Secre
Vincolato request payload
Mod. C: USB Wedge
FASE 03C Invia serialNumber
decifrato + Invio nel campo input dello Scanner Web
FASE 04 MOTORE VALIDAZIONE 14 REGOLE E MECCANICHE PASSINSTANCE (/scans)
Esegue regole Timbri/Punti/Prepagata/Check-In e invia push live APNs / Google

Architetture di lettori supportate ed enum NfcReaderMode

Passinstance supporta quattro modalità operative definite dall'enum backend NfcReaderMode attraverso i provider hardware supportati (reader provider: HID, ZEBRA, INGENICO, VERIFONE, PAX, SUNMI):

Enum NfcReaderModeComportamento di protocollo e compatibilità hardware
AUTOPolling automatico a doppio protocollo: il terminale alterna Apple VAS e Google Smart Tap entro una finestra di tap di 300ms (consigliato per certified NFC e terminali POS moderni).
KEYBOARD_WEDGEEmulazione tastiera USB HID: il lettore decifra il payload del pass sul dispositivo e digita serialNumber + Invio direttamente nel Web Scanner Passinstance o nella schermata POS.
APPLE_WALLETSolo polling Apple VAS dedicato; ottimizzato per ambienti esclusivamente iOS o tornelli rapidi a protocollo singolo.
GOOGLE_SMART_TAPSolo polling NDEF Google Smart Tap dedicato.

Famiglie hardware certificate

  1. 1
    Lettori certified NFC (NFC Terminal, NFC Terminal, NFC Terminal Wi-Fi/PoE): Lettori NFC dedicati ai pass Wallet mobile con supporto simultaneo alla decifratura Apple VAS e Google Smart Tap. Le unità NFC Pro inviano i tap decifrati direttamente a POST /api/v1/reader/validate con header firma HMAC x-reader-signature (o x-signature).
  2. 2
    Terminali Verifone, Ingenico, HID, Zebra, PAX e Sunmi: Terminali enterprise modellati tramite record reader provider e store location / POS terminal / hardware reader.
  3. 3
    Scanner ottici da banco 2D (fallback senza entitlement): I normali scanner ottici per codici a barre 2D (Zebra, Honeywell, Tera) che leggono codici QR/Aztec dei pass Wallet in modalità KEYBOARD_WEDGE offrono un avvio immediato senza approvazione di chiavi NFC Apple o Google.

Importante: I lettori che chiamano POST /api/v1/reader/redeem o /api/v1/reader/validate devono autenticarsi con X-Reader-Secret (reader integration secret), mentre i webhook cloud NFC che chiamano POST /api/v1/reader/validate firmano le richieste con x-reader-signature / x-signature.

Endpoint API per lettori hardware e terminali (Reader Management API / Reader Orchestration API)

MetodoPercorso endpointHeader AuthDescrizione
GET / POST/api/v1/reader/devicesBearer / Chiave APIElenca o registra dispositivi hardware reader certified NFC (GET/PUT/DELETE .../readers/:id e POST .../readers/:id/test).
GET/api/v1/reader/devices/:id/config-fileBearer / Chiave APIGenera un pacchetto config.txt pronto per il caricamento sui lettori certified NFC (VAS1MerchantID, ST1CollectorID, slot chiavi e URL webhook cloud).
POST/api/v1/reader/validatex-reader-signatureWebhook dedicato all'acquisizione dei tap per lettori cloud certified NFC Pro (reader event payload, più /events/batch per batch).
POST/api/v1/reader/validateX-Reader-SecretConvalida un ingresso tramite barcodeValue (request payload: customerId, barcodeValue, idempotencyKey, operatorId?, location?).
POST/api/v1/reader/redeemX-Reader-SecretElabora un riscatto tap idempotente (request payload: customerId, passId, amount?, idempotencyKey, operatorId?).

Esempio: riscatto da tap su lettore hardware (POST /api/v1/reader/redeem)

JSON
POST /api/v1/reader/redeem
Headers:
  X-Reader-Secret: <reader integration secret>
  Content-Type: application/json

{
  "customerId": "8f94d930-b302-4fc8-9f12-000000000001",
  "passId": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
  "amount": "12.50",
  "idempotencyKey": "tap_01J9Z9K2M4N6P8Q0R2S4",
  "operatorId": "term_checkout_lane_02"
}

Risposta (200 OK):

JSON
{
  "success": true,
  "resultingValue": "37.50"
}

Consulti Configurazione pass NFC, Apple VAS, Google Smart Tap e Configurazione dello scanner.

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.