Skip to content
Help Center Guide · Pass ScanningOnboarding Phase 4
3 min readVerified 2026-11-16

Scan Modes & Validation Rules

Configure one-time redeem, check-in/out, once-per-day constraints, staff feedback messages, and offline cache rules.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

After-scan message & Scanner configurations (Zoomed)

Customize the operator confirmation message using placeholders like {holderName} and manage active scanner access links.

Overview

Every scan submitted to POST /api/v1/scans is evaluated against the active ScannerConfiguration (resolved either from the bound x-scanner-key or scannerConfigurationId / validationConfigId in request payload) and a deterministic, 14-rule Validation Rules Engine pipeline. Together, these settings govern whether a pass records attendance, voids upon single use, toggles venue check-in state, mutates stored value, or enforces cryptographic anti-replay nonces.

Create scanner configuration modal
Create scanner configuration modal

Important: Validation rules execute atomically on the server. When a scan mutates pass state (such as VOIDED_AFTER_SCAN or StoredValueOperation.SUBTRACT), duplicate concurrent requests are serialized using idempotency locks (x-idempotency-key) to prevent race conditions across multiple registers.

Configuration & Outcome Enumerations

When configuring validation profiles in Scanner -> Scanner Configurations (/scanner/configs) or via /api/v1/validation/configs, five Passinstance database enumerations control terminal behavior and persisted scan outcomes:

1. ScanMode Enum

ScanMode ValueBehavior & State TransitionTypical Use Case
SAVE_ATTENDANCERecords a valid scan event and executes linked loyalty/stamp mechanics without voiding the pass.Multi-visit loyalty cards, gym memberships, season passes.
VOIDED_AFTER_SCANAtomically transitions pass status to VOIDED on the first valid scan; subsequent scans return ALREADY_VOIDED.Single-use coupons, promotional vouchers, one-time entry tickets.
INVALIDATE_AFTER_SCANMarks the pass invalidated after redemption and blocks future acceptance under the validation configuration.Single-redemption passes and restricted guest vouchers.
CHECK_INTransitions pass attendance state to checked-in; rejects repeat check-ins if already inside.Conference session entry, controlled-access gates.
CHECK_OUTTransitions pass attendance state from checked-in to checked-out.Venue exit tracking, capacity management.
CHECK_IN_CHECK_OUT_TOGGLEAutomatically alternates between CHECK_IN and CHECK_OUT on successive scans.Co-working spaces, multi-day festival wristbands/passes.

2. Stored Value, NFC & Scan Outcome Enumerations

Enum TypeAllowed ValuesPurpose
StoredValueOperationNONE, ADD, SUBTRACT, SETDefines whether a scan leaves balances untouched, tops up credit (ADD), debits purchase value (SUBTRACT), or overwrites balance (SET).
StoredValueAmountSourceFIXED, OPERATOR, MECHANICDetermines whether the transaction amount comes from a preset configuration value (FIXED), cashier prompt (OPERATOR), or template mechanic (MECHANIC).
NfcReaderModeAUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAPConfigures contactless reader protocol negotiation for Apple VAS and Google Smart Tap terminals.
scan actionINCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOPAction recorded on each pass-use or scan ledger transaction (request payload also permits SET).
scan statusSUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUTGranular persisted status stored on the Scan audit record (including explicit check-in/check-out transitions).

The 14-Rule Validation Rules Engine Pipeline

When POST /api/v1/scans receives a payload, Validation Rules Engine executes 14 prioritized validation rules across four stages (Core -> Mechanics -> Security -> Fallback):

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
14-RULE BUSINESS VALIDATION ENGINE PIPELINE
STAGE 01 POST/api/v1/scans (request payload + x-scanner-key)
STAGE 02 Stage 1: Core Rules
1
PassStatusRuleVerify pass is ACTIVE (not VOIDED / SUSPENDED)
2
ExpirationRuleVerify now() < expirationDate
3
TimeWindowRuleVerify scan falls within allowed schedule/hours
4
GeofencingRuleVerify scanner GPS {lat, lng} within radius
STAGE 03 Stage 2: Mechanics Rules
5
OncePerDayRuleReject if pass already scanned within rolling window
6
StampCardAddRuleIncrement stamp counter & evaluate milestone
7
StampCardDeductRuleDeduct stamps for reward redemption
8
PrepaidCardRuleExecute ADD / SUBTRACT / SET on stored value
9
LoyaltyProgramRuleCalculate & apply pointsDelta
10
TierEvaluationRuleUpgrade pass tier if threshold crossed
STAGE 04 Stage 3: Security Rules
11
RateLimitRulePrevent rapid scan flooding on a single pass
12
AntiReplayRuleVerify cryptographic scan nonce from /scans/prepare
13
DeviceValidationRuleVerify scanner key & terminal binding
STAGE 05 Stage 4: Fallback
14
DefaultAcceptanceRuleEmit decision: "SUCCESS", status: "ACCEPTED"

Every rule evaluated during a scan appends its execution result to the ruleTrace array in request payload, providing a complete diagnostic trail.

Anti-Replay Nonces (POST /api/v1/scans/prepare)

To protect high-value tickets and vouchers against static barcode screenshots, terminals can request a short-lived cryptographic scan nonce prior to final execution:

Request

POST /api/v1/scans/prepare
Header
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "scannedBarcodeValue": "PI-TKT-992014",
  "scannerConfigurationId": "scfg_main_entrance_01"
}

Response (201 Created)

JSON
{
  "success": true,
  "data": {
    "nonce": "snonce_8841a9c2f01e4b72",
    "expiresAt": "2026-11-15T22:35:30.000Z"
  }
}

Passing "nonce": "snonce_8841a9c2f01e4b72" inside the subsequent POST /api/v1/scans payload satisfies AntiReplayRule and immediately burns the nonce so it cannot be replayed.

Scan Execution Schema (POST /api/v1/scans)

request payload Payload

JSON
{
  "scannedBarcodeValue": "PI-LOY-449102",
  "scannerConfigurationId": "scfg_register_01",
  "nonce": "snonce_8841a9c2f01e4b72",
  "timestamp": "2026-11-15T22:35:10.000Z",
  "location": {
    "lat": 52.520008,
    "lng": 13.404954
  },
  "channel": "NFC",
  "protocol": "VAS",
  "validationData": {
    "amount": 18.50,
    "place": "Flagship Berlin Store"
  },
  "operatorId": "emp_cashier_07",
  "terminalId": "pos_term_berlin_02",
  "configurationVersion": 4
}

request payload Payload & Decision Codes

The engine returns one of seven canonical decision values: SUCCESS, FAILED, ALREADY_USED, ALREADY_VOIDED, EXPIRED, INVALID, or PENDING (when operator input is required via scanForm).

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "reasonCode": "RULE_ACCEPTED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true },
    { "rule": "ExpirationRule", "passed": true },
    { "rule": "LoyaltyProgramRule", "passed": true, "pointsDelta": 185 },
    { "rule": "TierEvaluationRule", "passed": true, "upgradedTo": "GOLD" }
  ],
  "passSnapshot": {
    "id": "pass_loy_449102",
    "templateId": "tmpl_loyalty_01",
    "serialNumber": "PI-LOY-449102",
    "externalId": "crm_cust_44910",
    "status": "ACTIVE",
    "tier": "GOLD",
    "barcodeValue": "PI-LOY-449102",
    "storedValue": "42.00"
  },
  "remainingBalance": "42.00",
  "effects": {
    "oldBalance": "42.00",
    "newBalance": "42.00",
    "pointsDelta": 185,
    "transactionAmount": 18.50,
    "currency": "EUR"
  },
  "display": {
    "title": "Scan Accepted — Gold Tier!",
    "subtitle": "+185 Points awarded",
    "color": "success"
  },
  "configurationVersion": 4,
  "configurationStale": false
}

For auditing completed scans and exporting CSV logs, see Scan History & Results.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.