Skip to content
Polaris Express Docs

Perform an NFC card scan

You’re an operator with the ExpresScan iPhone in hand and you need to capture a customer’s EV card so an admin in the web console can finish pairing it. This runbook walks the device side of that flow — what the phone should look like before the admin presses Tap to add, what happens when the scan request lands, and how to recover when the read fails.

Prerequisites

Section titled “Prerequisites”
  • ExpresScan is signed in to the right Polaris Express account. The Ready screen shows the brand and the “Ready to Scan” hero.
  • The status pill is not visible, or shows Online. Any other state (Connecting, Reconnecting, Offline) means the device isn’t receiving scan requests yet.
  • The admin who will trigger the scan has the customer’s account open in the web console and is about to press Tap to add in the EV cards panel.
  • The customer’s physical EV card is in reach. The app supports standard ISO 14443 cards; MIFARE Classic is not supported.

Procedure

Section titled “Procedure”

  1. Confirm the device is online

    Open ExpresScan and look at the Ready screen. If you see a status pill above the “How this works” disclosure, the device isn’t fully linked yet:

    • Connecting — the SSE link is being established. Wait a few seconds.
    • Reconnecting — the link dropped and is retrying. Wait, or tap the pill to open diagnostics.
    • Offline — the device has no network. Restore connectivity before continuing.

    When the device is healthy the pill disappears and the hero reads Ready to Scan.

  2. Have the admin start the pairing

    Ask the admin to press Tap to add on the customer’s record in the web console. The phone vibrates and the iOS NFC reader sheet opens automatically with the prompt Hold your card to the top of your iPhone.

    You have 60 seconds before the sheet times out, and the pairing itself expires 90 seconds after the admin pressed the button — whichever is shorter wins.

  3. Present the card

    Hold the EV card flat against the top edge of the iPhone (the NFC antenna sits just above the front camera on modern iPhones). Keep it still until you feel the success haptic.

    The screen advances to the success view showing the resolved card and account, and the admin’s console updates within ~1 second.

  4. Dismiss the result

    Tap Done on the success screen to return to Ready to Scan. There is no auto-dismiss — the result stays on screen until you acknowledge it, so the operator and customer can both confirm the right card was read.

Verify

Section titled “Verify”

You’ve completed a scan successfully when:

  • The phone shows the green success screen with the EV card details.
  • The admin’s web console closes the Tap to add modal and the new card appears on the customer’s record.
  • The Ready screen shows no pending upload badge. If you see “Saving your scans…” or “N pending upload”, the result hasn’t reached the server yet — see the next section.

To audit a completed scan from the web console, check the customer’s EV cards list and the audit log entry for the card-add event.

If something goes wrong

Section titled “If something goes wrong”

The iOS NFC sheet shows “Could not read card”

Section titled “The iOS NFC sheet shows “Could not read card””

The card is either an unsupported type or wasn’t held still long enough. The phone returns to Ready to Scan. Ask the admin to press Tap to add again and retry.

If the card is MIFARE Classic (common on older building access cards), it cannot be used as an EV card — the iOS NFC stack does not support it.

The user cancelled the iOS sheet

Section titled “The user cancelled the iOS sheet”

Tapping Cancel inside the system NFC sheet is the canonical cancel gesture. ExpresScan treats this as a full scan cancel and tells the server, so the admin’s Tap to add modal closes immediately. The phone returns to Ready to Scan.

The admin cancelled from the web

Section titled “The admin cancelled from the web”

If the admin closes the Tap to add modal while the NFC sheet is open, ExpresScan dismisses the system sheet automatically and returns to Ready to Scan. No error is shown — admin-cancel is normal flow.

”Pairing expired”

Section titled “”Pairing expired””

The 90-second pairing window elapsed before the card was read. Ask the admin to press Tap to add again. There is nothing to clean up — the pairing is server-side TTL’d.

”Network error” with a pending upload badge

Section titled “”Network error” with a pending upload badge”

The card read succeeded but the result POST to /api/devices/scan-result failed. ExpresScan queues the result locally and retries when the link recovers; the N pending upload badge on the Ready screen tracks the queue depth.

”Signed out by an admin”

Section titled “”Signed out by an admin””

An admin revoked this device’s token, or another device claimed the same registration. ExpresScan wipes its credentials and returns to the welcome screen. Re-register the device before attempting another scan.

The Ready screen is stuck on “Reconnecting”

Section titled “The Ready screen is stuck on “Reconnecting””

Tap the Reconnecting pill to open the diagnostics sheet and check the last heartbeat time and reconnect count. If reconnects keep piling up, the device has a flaky network — move it to a known-good Wi-Fi or restart the app.

Audit and reversibility

Section titled “Audit and reversibility”

NFC scans are read-only at the device layer: the phone signs an idTag with the device secret and POSTs it to the backend. The phone itself doesn’t modify customer records — the web admin’s Tap to add confirmation is what writes the card to the database.

To reverse a card-add, remove the EV card from the customer’s record in the web console. The original scan event remains in the audit log for forensic review.

Section titled “Related”