How scanning works
Updated November 18, 2026
When someone presents a pass at the door, till, or gate, a paired scanner reads the barcode and checks it against Passmint in real time. Every scan follows the same three steps: scan, verify, redeem.
1. Scan
A scanner reads the pass's barcode and sends it to POST /v1/scan. The scanner is
either the Passmint Scanner app on an iPhone or iPad, or a device or
integration of your own connected to the Passmint API. Both use a
paired token. By default, the barcode message is
{{serialNumber}}, the pass's unique serial number, so scanning it identifies
exactly one pass. If your template's barcode encodes something else, see
barcodes on passes.
2. Verify
POST /v1/scan looks up the pass and checks it against a few conditions before
deciding whether to accept the scan:
- Does a pass with this code exist in the scanner's workspace?
- Is the pass in the same mode (test or live) as the scanner?
- If the scanner is scoped to one template, does the pass belong to that template?
- Has the pass been voided?
- Does the pass's redemption policy still allow one more scan?
Passmint's servers make this check, so a scanner asks them first.
When the connection drops
Passmint Scanner keeps a list of the passes it may check on the phone. If it can't get an answer from the server in time, it checks that list instead, shows the result, and queues the scan. Queued scans upload when the phone is back online, and each one is counted once.
If a pass isn't in the stored list, the app says it can't verify it offline and leaves the decision to the person at the door. The server checks every offline decision when it uploads. Any that it would have decided differently, such as two phones admitting the same single-use ticket while both were offline, are listed under Offline conflicts on the scanner setup's page in the dashboard.
If you call POST /v1/scan from your own integration, that call needs a connection.
3. Redeem
If every check passes, Passmint records the scan as accepted, increments the pass's redeemed count, and, for a single-use policy, marks the pass as redeemed so it can't be scanned again. If any check fails, the scan is rejected and nothing on the pass changes.
Either way, the scan is written to the pass's redemption log so you can see exactly what happened and when.
What a rejection means
A rejected scan always comes with a reason:
- Already redeemed: the pass has a single-use policy and has already been scanned once.
- Use limit reached: the pass has a count-limited policy and has already been scanned its maximum number of times.
- Voided: the pass was voided from the dashboard or the API and can no longer be redeemed.
- Wrong mode: a test-mode pass was scanned by a live scanner, or the reverse. Test and live are kept separate on purpose, so rehearsing with test passes can never redeem a real one.
- Out of scope: the scanner is scoped to a specific template, and the scanned pass belongs to a different one.
- Not found: the scanned code doesn't match any pass in the workspace.
If the scanner setup allows it, the person at the door can choose Admit anyway on a rejected pass. That scan is accepted and logged as an override, so it's clear later that it was a deliberate choice. A voided pass can never be admitted this way.
Rejected scans are still written to the redemption log with their reason. See the redemption log for how to read it.
Accepted scans fire an event
An accepted scan emits a pass.redeemed event through Passmint's webhook pipeline,
the same system that delivers install and update events. Subscribe to it to react to
redemptions in your own systems (attendance tracking, loyalty points, and so on). A
rejected scan does not fire this event; it's only logged. See the
webhooks reference for the full event payload and how to subscribe.