Overzicht: contactloze lezerhardware selecteren & koppelen
Omdat iOS- en Android-smartphones voor consumenten directe host-card-emulatie beperken en cryptografische terminal-handshakes vereisen voor closed-loop walletpassen, is voor echte tap-to-redeem lezerhardware vereist met ondersteuning voor Apple VAS + Google Smart Tap. Passinstance modelleert en authenticeert fysieke lezerparken rechtstreeks via de database-entiteiten hardware reader, reader device, store location en POS terminal.
Ondersteunde lezerarchitecturen & NfcReaderMode
Passinstance ondersteunt vier operationele modi zoals gedefinieerd door de backend-enum NfcReaderMode over de ondersteunde hardwareproviders (reader provider: HID, ZEBRA, INGENICO, VERIFONE, PAX, SUNMI):
NfcReaderMode-enum | Protocolgedrag & geschikte hardware |
|---|---|
AUTO | Automatisch dual-protocol pollen: de terminal wisselt binnen één tapvenster van 300 ms af tussen Apple VAS en Google Smart Tap (aanbevolen voor certified NFC en moderne POS-terminals). |
KEYBOARD_WEDGE | USB HID-toetsenbordemulatie: de lezer ontsleutelt de paspayload op het apparaat en typt het serialNumber + Enter rechtstreeks in de Passinstance Web Scanner of het POS-kassascherm. |
APPLE_WALLET | Uitsluitend Apple VAS-pollen; geoptimaliseerd voor omgevingen met alleen iOS of snelle single-protocol toegangspoorten. |
GOOGLE_SMART_TAP | Uitsluitend Google Smart Tap NDEF-pollen. |
Gecertificeerde hardwarefamilies
-
1
certified NFC-lezers (
NFC Terminal,NFC Terminal,NFC TerminalWi-Fi/PoE): speciaal gebouwde NFC-lezers voor mobiele wallets die gelijktijdige ontsleuteling van Apple VAS en Google Smart Tap ondersteunen. NFC Pro-units sturen ontsleutelde taps rechtstreeks door naarPOST /api/v1/reader/validatemet de HMAC-handtekeningheaderx-reader-signature(ofx-signature). -
2
Verifone-, Ingenico-, HID-, Zebra-, PAX- & Sunmi-terminals: enterprise-terminals gemodelleerd via reader provider en de records
store location,POS terminalenhardware reader. -
3
2D optische baliescanners (terugvaloptie zonder entitlements): standaard optische 2D-barcodescanners (Zebra, Honeywell, Tera) die Wallet QR-/Aztec-codes lezen in de modus
KEYBOARD_WEDGEbieden directe inzetbaarheid zonder Apple- of Google NFC-sleutelgoedkeuring.
Belangrijk: Lezers die
POST /api/v1/reader/redeemof/api/v1/reader/validateaanroepen, moeten zich authenticeren metX-Reader-Secret(reader integration secret), terwijl NFC cloud-webhooks diePOST /api/v1/reader/validateaanroepen hun verzoeken ondertekenen metx-reader-signature/x-signature.
API-endpoints voor hardwarelezers & terminals (Reader Management API / Reader Orchestration API)
| Methode | Endpoint-pad | Auth-header | Beschrijving |
|---|---|---|---|
GET / POST | /api/v1/reader/devices | Bearer / API Key | Geeft een overzicht van of registreert certified NFC hardware reader-apparaten (GET/PUT/DELETE .../readers/:id en POST .../readers/:id/test). |
| GET | /api/v1/reader/devices/:id/config-file | Bearer / API Key | Genereert een kant-en-klare config.txt-bundel voor certified NFC-lezers (VAS1MerchantID, ST1CollectorID, sleutelslots en cloud-webhook-URL). |
| POST | /api/v1/reader/validate | x-reader-signature | Specifieke webhook voor tapinvoer van certified NFC Pro cloud-lezers (reader event payload, plus batch /events/batch). |
| POST | /api/v1/reader/validate | X-Reader-Secret | Valideert een invoer op barcodeValue (request payload: customerId, barcodeValue, idempotencyKey, operatorId?, location?). |
| POST | /api/v1/reader/redeem | X-Reader-Secret | Verwerkt een idempotente tap-inwisseling (request payload: customerId, passId, amount?, idempotencyKey, operatorId?). |
Voorbeeld: tap-inwisseling via hardwarelezer (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"
}
Antwoord (200 OK):
{
"success": true,
"resultingValue": "37.50"
}
Bekijk NFC-pasconfiguratie, Apple VAS, Google Smart Tap en Scannerconfiguratie & -instellingen.
