Überblick: Kontaktlose Lesehardware auswählen & koppeln
Da iOS- und Android-Smartphones im Verbraucherbereich eine rohe Host-Card-Emulation einschränken und für geschlossene Wallet-Pässe kryptografische Terminal-Handshakes vorschreiben, erfordert echtes Tap-to-Redeem Apple-VAS- und Google-Smart-Tap-fähige Lesehardware. Passinstance bildet physische Lesegeräteflotten nativ über die Datenbank-Entitäten hardware reader, reader device, store location und POS terminal ab und authentifiziert deren Zugriffe.
Unterstützte Reader-Architekturen & NfcReaderMode
Passinstance unterstützt vier Betriebsmodi gemäß dem Backend-Enum NfcReaderMode über alle angebundenen Hardware-Anbieter hinweg (reader provider: HID, ZEBRA, INGENICO, VERIFONE, PAX, SUNMI):
NfcReaderMode-Enum | Protokollverhalten & Hardware-Eignung |
|---|---|
AUTO | Automatisches Dual-Protokoll-Polling: Das Terminal wechselt innerhalb eines einzigen 300-ms-Tap-Fensters automatisch zwischen Apple VAS und Google Smart Tap (empfohlen für certified NFC und moderne POS-Terminals). |
KEYBOARD_WEDGE | USB-HID-Tastaturemulation: Das Lesegerät entschlüsselt das Pass-Payload direkt auf dem Gerät und tippt die serialNumber + Enter unmittelbar in den Passinstance-Web-Scanner oder die POS-Kassenoberfläche ein. |
APPLE_WALLET | Dediziertes Apple-VAS-Polling; optimiert für reine iOS-Umgebungen oder extrem schnelle Einzelprotokoll-Drehkreuze. |
GOOGLE_SMART_TAP | Dediziertes Google-Smart-Tap-NDEF-Polling. |
Zertifizierte Hardware-Familien
-
1
certified NFC-Lesegeräte (
NFC Terminal,NFC Terminal,NFC TerminalWLAN/PoE): Speziell für Mobile-Wallet-Pässe entwickelte NFC-Reader mit gleichzeitiger Apple-VAS- und Google-Smart-Tap-Entschlüsselung. NFC-Hardware-Einheiten senden entschlüsselte Taps direkt per HTTP anPOST /api/v1/reader/validatemit dem HMAC-Signaturheaderx-reader-signature(oderx-signature). -
2
Verifone-, Ingenico-, HID-, Zebra-, PAX- & Sunmi-Terminals: Enterprise-Kassen- und Zutrittsterminals, modelliert über reader provider sowie
store location- /POS terminal- /hardware reader-Datensätze. -
3
Optische 2D-Kassenscanner (Fallback ohne Entitlement): Herkömmliche 2D-Barcode-Scanner (Zebra, Honeywell, Tera), die Wallet-QR- oder Aztec-Codes im
KEYBOARD_WEDGE-Modus lesen, ermöglichen den sofortigen Produktivstart ganz ohne Apple-/Google-NFC-Schlüsselanträge.
Wichtig: Lesegeräte, die
POST /api/v1/reader/redeemoder/api/v1/reader/validateaufrufen, müssen sich mitX-Reader-Secret(reader integration secret) authentifizieren, während NFC-Cloud-Webhooks anPOST /api/v1/reader/validateihre Anfragen mitx-reader-signature/x-signaturesignieren.
API-Endpunkte für Hardware-Lesegeräte & Terminals (Reader Management API / Reader Orchestration API)
| Methode | Endpunkt-Pfad | Auth-Header | Beschreibung |
|---|---|---|---|
GET / POST | /api/v1/reader/devices | Bearer / API Key | Listet certified NFC-hardware reader-Geräte auf oder registriert neue (GET/PUT/DELETE .../readers/:id sowie POST .../readers/:id/test). |
| GET | /api/v1/reader/devices/:id/config-file | Bearer / API Key | Erzeugt ein einspielbereites config.txt-Paket für certified NFC-Leser (VAS1MerchantID, ST1CollectorID, Schlüssel-Slots und Cloud-Webhook-URL). |
| POST | /api/v1/reader/validate | x-reader-signature | Dedizierter Webhook zur Tap-Erfassung durch certified NFC Pro Cloud-Reader (reader event payload, plus Batch /events/batch). |
| POST | /api/v1/reader/validate | X-Reader-Secret | Validiert einen Eintrag anhand von barcodeValue (request payload: customerId, barcodeValue, idempotencyKey, operatorId?, location?). |
| POST | /api/v1/reader/redeem | X-Reader-Secret | Verarbeitet eine idempotente Tap-Einlösung (request payload: customerId, passId, amount?, idempotencyKey, operatorId?). |
Beispiel: Tap-Einlösung über Hardware-Lesegerät (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"
}
Antwort (200 OK):
{
"success": true,
"resultingValue": "37.50"
}
Lesen Sie NFC-Pass-Konfiguration, Apple VAS, Google Smart Tap sowie Scanner-Einrichtung & Konfiguration.
