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.
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 NfcReaderMode | Comportamento di protocollo e compatibilità hardware |
|---|---|
AUTO | Polling 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_WEDGE | Emulazione 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_WALLET | Solo polling Apple VAS dedicato; ottimizzato per ambienti esclusivamente iOS o tornelli rapidi a protocollo singolo. |
GOOGLE_SMART_TAP | Solo polling NDEF Google Smart Tap dedicato. |
Famiglie hardware certificate
-
1
Lettori certified NFC (
NFC Terminal,NFC Terminal,NFC TerminalWi-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 aPOST /api/v1/reader/validatecon header firma HMACx-reader-signature(ox-signature). -
2
Terminali Verifone, Ingenico, HID, Zebra, PAX e Sunmi: Terminali enterprise modellati tramite record reader provider e
store location/POS terminal/hardware reader. -
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_WEDGEoffrono un avvio immediato senza approvazione di chiavi NFC Apple o Google.
Importante: I lettori che chiamano
POST /api/v1/reader/redeemo/api/v1/reader/validatedevono autenticarsi conX-Reader-Secret(reader integration secret), mentre i webhook cloud NFC che chiamanoPOST /api/v1/reader/validatefirmano le richieste conx-reader-signature/x-signature.
Endpoint API per lettori hardware e terminali (Reader Management API / Reader Orchestration API)
| Metodo | Percorso endpoint | Header Auth | Descrizione |
|---|---|---|---|
GET / POST | /api/v1/reader/devices | Bearer / Chiave API | Elenca o registra dispositivi hardware reader certified NFC (GET/PUT/DELETE .../readers/:id e POST .../readers/:id/test). |
| GET | /api/v1/reader/devices/:id/config-file | Bearer / Chiave API | Genera un pacchetto config.txt pronto per il caricamento sui lettori certified NFC (VAS1MerchantID, ST1CollectorID, slot chiavi e URL webhook cloud). |
| POST | /api/v1/reader/validate | x-reader-signature | Webhook dedicato all'acquisizione dei tap per lettori cloud certified NFC Pro (reader event payload, più /events/batch per batch). |
| POST | /api/v1/reader/validate | X-Reader-Secret | Convalida un ingresso tramite barcodeValue (request payload: customerId, barcodeValue, idempotencyKey, operatorId?, location?). |
| POST | /api/v1/reader/redeem | X-Reader-Secret | Elabora un riscatto tap idempotente (request payload: customerId, passId, amount?, idempotencyKey, operatorId?). |
Esempio: riscatto da tap su lettore hardware (POST /api/v1/reader/redeem)
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):
{
"success": true,
"resultingValue": "37.50"
}
Consulti Configurazione pass NFC, Apple VAS, Google Smart Tap e Configurazione dello scanner.
