Aperçu : choisir et appairer le matériel lecteur sans contact
Parce que les smartphones grand public iOS et Android restreignent l'émulation de carte brute et exigent une poignée de main cryptographique avec le terminal pour les passes Wallet en boucle fermée, une véritable lecture par passage sans contact nécessite du matériel lecteur Apple VAS + Google Smart Tap. Passinstance modélise et authentifie nativement les parcs de terminaux physiques via les entités hardware reader, reader device, store location et POS terminal.
Architectures lecteurs prises en charge & modes NfcReaderMode
Passinstance gère quatre modes de fonctionnement définis par l'énumération backend NfcReaderMode sur les constructeurs supportés (reader provider : HID, ZEBRA, INGENICO, VERIFONE, PAX, SUNMI) :
Valeur NfcReaderMode | Protocole & adéquation matérielle |
|---|---|
AUTO | Scrutation automatique double protocole : le terminal alterne entre Apple VAS et Google Smart Tap dans une fenêtre de 300 ms (recommandé pour certified NFC et les TPE modernes). |
KEYBOARD_WEDGE | Émulation clavier USB HID : le lecteur déchiffre localement le passe puis saisit le serialNumber suivi de Entrée directement dans le Scanner Web Passinstance ou l'écran de caisse. |
APPLE_WALLET | Scrutation dédiée Apple VAS uniquement ; optimisée pour les environnements exclusifs iOS ou les portiques à haut débit mono-protocole. |
GOOGLE_SMART_TAP | Scrutation NDEF dédiée Google Smart Tap uniquement. |
Familles matérielles certifiées
-
1
Lecteurs certified NFC (
NFC Terminal,NFC Terminal,NFC TerminalWi-Fi/PoE) : Lecteurs NFC dédiés aux portefeuilles mobiles supportant le déchiffrement simultané Apple VAS et Google Smart Tap. Les boîtiers NFC Pro publient directement les passages déchiffrés surPOST /api/v1/reader/validateavec l'en-tête de signature HMACx-reader-signature(oux-signature). -
2
Terminaux Verifone, Ingenico, HID, Zebra, PAX & Sunmi : Terminaux professionnels modélisés via reader provider et les enregistrements
store location/POS terminal/hardware reader. -
3
Douchettes optiques 2D de comptoir (solution immédiate sans agrément) : Les lecteurs optiques 2D standard (Zebra, Honeywell, Tera) lisant les codes QR/Aztec Wallet en mode
KEYBOARD_WEDGEpermettent un déploiement instantané sans aucune demande de clés NFC Apple ou Google.
Important : Les lecteurs appelant
POST /api/v1/reader/redeemou/api/v1/reader/validatedoivent s'authentifier via l'en-têteX-Reader-Secret(reader integration secret), tandis que les webhooks cloud NFC surPOST /api/v1/reader/validatesignent leurs requêtes avecx-reader-signature/x-signature.
Points d'entrée API des lecteurs & terminaux (Reader Management API / Reader Orchestration API)
| Méthode | Chemin du point d'entrée | En-tête d'auth | Description |
|---|---|---|---|
GET / POST | /api/v1/reader/devices | Bearer / API Key | Liste ou enregistre les équipements hardware reader certified NFC (GET/PUT/DELETE .../readers/:id et POST .../readers/:id/test). |
| GET | /api/v1/reader/devices/:id/config-file | Bearer / API Key | Génère un fichier config.txt prêt à charger pour lecteurs certified NFC (VAS1MerchantID, ST1CollectorID, emplacements de clés et URL webhook cloud). |
| POST | /api/v1/reader/validate | x-reader-signature | Webhook d'ingestion dédié aux lecteurs cloud certified NFC Pro (reader event payload, et lots sur /events/batch). |
| POST | /api/v1/reader/validate | X-Reader-Secret | Valide une entrée à partir de barcodeValue (request payload : customerId, barcodeValue, idempotencyKey, operatorId?, location?). |
| POST | /api/v1/reader/redeem | X-Reader-Secret | Exécute un encaissement sans contact idempotent (request payload : customerId, passId, amount?, idempotencyKey, operatorId?). |
Exemple : validation sans contact depuis un lecteur matériel (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"
}
Réponse (200 OK) :
{
"success": true,
"resultingValue": "37.50"
}
Consultez Configuration des passes NFC, Apple VAS, Google Smart Tap et Configuration du Scanner.
