Overview
Every barcode scan or contactless NFC tap processed through the Mobile Scanner App, Web Scanner, POS Integration (POST /v1/pos/redeem and POST /v1/pos/scan), Hardware Reader Orchestration (POST /api/v1/reader/redeem), or Scanner Runtime API (POST /api/v1/scans) generates an immutable, cryptographically traceable audit record. Scanning & Redemption Reports (/scanner in the Dashboard and /api/v1/validation/scans) aggregate these events across scanner configurations, physical validation places, operator IDs, and mechanic ledgers to give operations managers complete floor visibility.
Scan Telemetry & Rules Trace Pipeline
Important: Every scan response records a complete
ruleTracearray alongsideoperatorId,terminalId,scannerConfigurationId,externalId, and GPSlocationcoordinates—allowing compliance teams to audit exactly why a scan was accepted or rejected.
Scan Metric Definitions, scan status & PosOperation Breakdown
Passinstance categorizes validation traffic into canonical KPI buckets defined in PASS_ANALYTICS_METRIC_DEFINITIONS, backed by decision in the scan response and Passinstance database scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT):
| Metric Key | Underlying decision / scan status | Operational Meaning |
|---|---|---|
totalScans | All scan events | Total barcode or NFC presentations received by the validation engine within the reporting period. |
successfulScans | decision: 'SUCCESS' (SUCCESS, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS) | Scans that passed all 14 validation rules and executed their configured attendance or mechanic action (scan action). |
duplicateScans | decision: 'ALREADY_USED' or 'ALREADY_VOIDED' (ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT) | Replay attempts on single-use coupons (VOIDED_AFTER_SCAN scan mode) or passes already checked in/out. |
expiredScans | decision: 'EXPIRED' (EXPIRED) | Presentations of passes whose expirationDate has elapsed. |
rejectedScans | decision: 'INVALID' (INVALID) | Unrecognized barcode payloads, cross-tenant serial mismatches, or invalid cryptographic NFC signatures. |
failedScans | decision: 'FAILED' (FAILED: e.g., OUT_OF_BALANCE, COOLDOWN_ACTIVE) | Valid passes rejected by a business rule violation such as insufficient prepaid balance, geofence mismatch, or OncePerDayRule cooldown. |
For integrated retail registers hitting POST /v1/pos/redeem, transactions also record PosOperation (DISCOUNT | ADD_POINTS | DEDUCT_VALUE | ADD_STAMPS | VOID | CUSTOM) and walletPropagation (PosWalletPropagationStatus: QUEUED | SKIPPED), inspectable via GET /v1/pos/admin/logs.
Dimensional Reporting: Places, Configurations, and Operators
Validation reports can be filtered and grouped across five operational dimensions:
-
1
Scanner Configuration (
scannerConfigurationId): Compare throughput across distinct profiles (e.g., VIP Gate Check-In usingCHECK_IN scan modevs. Cafe Cashier Stamp Add usingStampCardAddRule). -
2
Validation Place & Geofence: Group redemptions by store branch, venue entrance, or GPS coordinate radius to measure foot traffic per physical site.
-
3
Operator & Terminal (
operatorId,terminalId): Audit scan volume and manual amount entries per cashier, device name (deviceName), or POS register. -
4
Channel & Protocol (
channel,protocol): Track optical scans (QR,PDF417,CODE128,AZTEC) versus contactless tap presentations (NFCviaVAS,SMART_TAP,NDEF, orJWT). -
5
Stored-Value & Loyalty Ledger Effects (
effects): Reconcile totalstampsAdded, netpointsDelta, and financialtransactionAmountcredits/debits by currency (ISO-4217).
Inspecting Scan Audit Logs & Ledger Effects via API
Recorded Scan Event & Ledger Payload Schema
When querying scan history (GET /api/v1/validation/configs/:id/scans or GET /api/v1/scans/result/:scanId), each event provides full diagnostic and financial context:
GET /api/v1/scans/result/scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c HTTP/1.1
Host: api.passinstance.com
x-scanner-key: <scanner_api_key>
Response Payload (200 OK)
{
"scanId": "scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c",
"timestamp": "2026-11-16T08:42:11.304Z",
"decision": "SUCCESS",
"status": "ACCEPTED",
"reasonCode": null,
"channel": "NFC",
"protocol": "VAS",
"resolvedConfigId": "cfg_7d82a100-3c4b-4e12-9a88-112233445566",
"passSnapshot": {
"id": "pas_55a19c88-102b-4f33-8d99-ccddff001122",
"templateId": "b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"serialNumber": "PI-2026-994812",
"externalId": "CRM-88210",
"status": "ACTIVE",
"tier": "GOLD"
},
"effects": {
"oldBalance": "45.00",
"newBalance": "32.50",
"transactionAmount": 12.50,
"currency": "EUR",
"amountBalanceBehavior": "ADD_VALUE",
"pointsDelta": 125,
"stampsAdded": 0
},
"ruleTrace": [
{ "rule": "PassStatusRule", "passed": true },
{ "rule": "ExpirationRule", "passed": true },
{ "rule": "PrepaidCardRule", "passed": true, "deducted": 12.50 },
{ "rule": "LoyaltyProgramRule", "passed": true, "awardedPoints": 125 }
]
}
Related Documentation
-
Export full scan histories and scanner key inventories in Data Exports & Reporting.
-
Explore workspace telemetry charts in Analytics Dashboard.
