Overview
Digital wallet coupons and vouchers live alongside payment cards on a customer's smartphone lock screen, driving significantly higher redemption rates than email discount codes or paper vouchers. Passinstance provides cryptographic protection, single-use anti-fraud verification, and real-time card voiding upon counter redemption.
Backend Architecture & Pass Type Mapping
In the Passinstance backend, coupon programs map to the official Apple Wallet and Google Wallet coupon primitives:
-
Pass Type (pass type):
coupon(uses Apple's native coupon layout with a prominent visual discount badge). -
Catalog Demo Blueprint:
promotional-coupon(available during onboarding). -
Default Validation Mode:
VOIDED_AFTER_SCAN scan mode. -
Primary Domain Constraints:
- limitToOneActivePerPass: true: Restricts smart download links to a single device, preventing discount link sharing across groups. - expirationDate: W3C ISO 8601 timestamp that automatically triggers native lock-screen expiry notifications. - addSecurityAnimation: true: Renders a dynamic holographic border around 2D barcodes to prevent fraudulent static screenshot presentation.
Redemption & Anti-Fraud Execution
The counter redemption workflow enforces strict single-use integrity through atomic database transactions in Pass Mechanics Engine:
Preventing Screenshot & Replay Fraud
When a cashier scans the coupon barcode:
-
1
The scanner dispatches a request to
POST /api/v1/scanscontainingscannedBarcodeValueand the scanner's secretx-scanner-key. -
2
The server confirms the pass status is
ACTIVEand that the current timestamp is prior toexpirationDate. -
3
If valid, the database atomically transitions the pass status to
VOIDED, assignsvoidReason: "SCANNED_AT_CHECKOUT", and logs the scan transaction. -
4
If an operator or bad actor scans the same pass barcode again, the validation engine rejects the transaction immediately with decision code
ALREADY_VOIDEDand error messagePASS_VOIDED_AFTER_SCAN. -
5
Simultaneously, Passinstance enqueues a background push notification to Apple APNs and Google Wallet. The pass on the customer's phone immediately greys out with a visible "Redeemed" watermark, preventing reuse at another register.
Concrete Scan Request & Response DTOs
Point-of-Sale systems, scanner terminals, and e-commerce checkouts interact with the validation endpoint:
HTTP Request
/api/v1/scans
{
"scannedBarcodeValue": "PI-CPN-849201",
"operatorId": "emp_sarah_m"
}
HTTP Response (200 OK)
{
"decision": "SUCCESS",
"status": "ACCEPTED",
"passSnapshot": {
"id": "pass_cpn_849201",
"templateId": "tmpl_coupon_7712",
"serialNumber": "PI-CPN-849201",
"status": "VOIDED",
"attributes": {
"discount": "25% OFF",
"terms": "Valid on purchases over €50"
}
}
}
Campaign Distribution Safeguards
When distributing coupons via public PassFlow pages, API creation, or SMS campaigns:
-
Download Expiry (
enableDownloadUntil): Set a strict date-time ("YYYY-MM-DD HH:mm"or ISO timestamp onrequest payload/ template config) after which unclaimed download links return HTTP 410 Gone. -
Access PIN Protection: Protect high-value promotional links with an access PIN (
?pin=orX-Wallet-Experience-Pin) delivered via SMS or purchase receipt. -
CRM & E-Commerce Correlation (
externalId): Pass anexternalId(e.g.order_88412_cpn) onPOST /api/v1/passesor/api/v1/passes/upsert-by-external-idso single-use voucher redemptions can be reconciled cleanly in your order system. -
Single-Device Link Binding: Enable
limitToOneActivePerPassso each customer's serialized download link locks to the first registered device rather than circulating across public groups.
Important:
VOIDED_AFTER_SCAN scan modevoids the pass immediately after a valid scan, whereasINVALIDATE_AFTER_SCAN scan modesets the status toINACTIVE/REDEEMED. Always verify whichScanModematches your accounting and wallet display requirements.
Learn more on our Coupons & Vouchers Overview.
