Overview: Selecting & Pairing Contactless Reader Hardware
Because consumer iOS and Android smartphones restrict raw host-card emulation and require cryptographic terminal handshakes for closed-loop wallet passes, true tap-to-redeem requires Apple VAS + Google Smart Tap reader hardware. Passinstance natively models and authenticates physical reader estates through the hardware reader, reader device, store location, and POS terminal database entities.
Supported Reader Architectures & NfcReaderMode
Passinstance supports four operational modes defined by the backend NfcReaderMode enum across supported hardware providers (reader provider: HID, ZEBRA, INGENICO, VERIFONE, PAX, SUNMI):
NfcReaderMode Enum | Protocol Behavior & Hardware Fit |
|---|---|
AUTO | Dual-protocol automatic polling: terminal alternates between Apple VAS and Google Smart Tap within a single 300ms tap window (recommended for certified NFC and modern POS terminals). |
KEYBOARD_WEDGE | USB HID keyboard emulation: the reader decrypts the pass payload on-device and types the serialNumber + Enter directly into the Passinstance Web Scanner or POS checkout screen. |
APPLE_WALLET | Dedicated Apple VAS polling only; optimized for iOS-exclusive environments or fast single-protocol turnstiles. |
GOOGLE_SMART_TAP | Dedicated Google Smart Tap NDEF polling only. |
Certified Hardware Families
-
1
certified NFC Readers (
NFC Terminal,NFC Terminal,NFC TerminalWi-Fi/PoE): Purpose-built mobile wallet NFC readers supporting simultaneous Apple VAS and Google Smart Tap decryption. NFC Pro units post decrypted taps directly toPOST /api/v1/reader/validatewith HMAC signature headerx-reader-signature(orx-signature). -
2
Verifone, Ingenico, HID, Zebra, PAX & Sunmi Terminals: Enterprise terminals modeled via reader provider and
store location/POS terminal/hardware readerrecords. -
3
2D Optical Counter Scanners (Zero-Entitlement Fallback): Standard 2D optical barcode scanners (Zebra, Honeywell, Tera) reading Wallet QR/Aztec codes in
KEYBOARD_WEDGEmode provide instant deployment with zero Apple/Google NFC key approvals.
Important: Readers calling
POST /api/v1/reader/redeemor/api/v1/reader/validatemust authenticate usingX-Reader-Secret(reader integration secret), whereas NFC cloud webhooks callingPOST /api/v1/reader/validatesign requests withx-reader-signature/x-signature.
Hardware Reader & Terminal API Endpoints (Reader Management API / Reader Orchestration API)
| Method | Endpoint Path | Auth Header | Description |
|---|---|---|---|
GET / POST | /api/v1/reader/devices | Bearer / API Key | Lists or registers certified NFC hardware reader devices (GET/PUT/DELETE .../readers/:id and POST .../readers/:id/test). |
| GET | /api/v1/reader/devices/:id/config-file | Bearer / API Key | Generates a ready-to-load config.txt bundle for certified NFC readers (VAS1MerchantID, ST1CollectorID, key slots, and cloud webhook URL). |
| POST | /api/v1/reader/validate | x-reader-signature | Dedicated tap ingestion webhook for certified NFC Pro cloud readers (reader event payload, plus batch /events/batch). |
| POST | /api/v1/reader/validate | X-Reader-Secret | Validates an entry by barcodeValue (request payload: customerId, barcodeValue, idempotencyKey, operatorId?, location?). |
| POST | /api/v1/reader/redeem | X-Reader-Secret | Processes an idempotent tap redemption (request payload: customerId, passId, amount?, idempotencyKey, operatorId?). |
Example: Hardware Reader Tap Redemption (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"
}
Response (200 OK):
{
"success": true,
"resultingValue": "37.50"
}
Review NFC Pass Configuration, Apple VAS, Google Smart Tap, and Scanner Setup & Configuration.
