Skip to content
Help Center Guide
3 min readVerified 2026-11-16

Coupons & Vouchers

Launch single-use or time-boxed promotional offers with scan validation and post-redemption expiration.

In This Guide

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:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
COUPON REDEMPTION & VOIDING
PARTICIPATING SYSTEM ACTORS
P1 Customer Wallet Pass
P2 Scanner / POS Terminal
P3 Passinstance Core API
STEP 1 REQUEST / ACTION Present Barcode QR
›
(PI-CPN-849201)
STEP 2 REQUEST / ACTION POST/api/v1/scans
›
Header: x-scanner-key
›
Body: {scannedBarcodeVal}
STEP 3 REQUEST / ACTION Verify status === ACTIVE
STEP 4 REQUEST / ACTION Check expirationDate >= now()
STEP 5 REQUEST / ACTION Atomic Update:
›
status = VOIDED,
›
oidedAt = now()
STEP 6 RESPONSE 200 OK
STEP 7 REQUEST / ACTION APNs Push & Google PATCH
›
{ decision: "SUCCESS",
›
(Silent update to device)
STEP 8 RESPONSE Card Greyed Out & Voided ====== status: "ACCEPTED" }

Preventing Screenshot & Replay Fraud

When a cashier scans the coupon barcode:

  1. 1
    The scanner dispatches a request to POST /api/v1/scans containing scannedBarcodeValue and the scanner's secret x-scanner-key.
  2. 2
    The server confirms the pass status is ACTIVE and that the current timestamp is prior to expirationDate.
  3. 3
    If valid, the database atomically transitions the pass status to VOIDED, assigns voidReason: "SCANNED_AT_CHECKOUT", and logs the scan transaction.
  4. 4
    If an operator or bad actor scans the same pass barcode again, the validation engine rejects the transaction immediately with decision code ALREADY_VOIDED and error message PASS_VOIDED_AFTER_SCAN.
  5. 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

POST /api/v1/scans
Headers
x-scanner-key sk_live_counter_register_04
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "PI-CPN-849201",
  "operatorId": "emp_sarah_m"
}

HTTP Response (200 OK)

JSON
{
  "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 on request 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= or X-Wallet-Experience-Pin) delivered via SMS or purchase receipt.
  • CRM & E-Commerce Correlation (externalId): Pass an externalId (e.g. order_88412_cpn) on POST /api/v1/passes or /api/v1/passes/upsert-by-external-id so single-use voucher redemptions can be reconciled cleanly in your order system.
  • Single-Device Link Binding: Enable limitToOneActivePerPass so each customer's serialized download link locks to the first registered device rather than circulating across public groups.

Important: VOIDED_AFTER_SCAN scan mode voids the pass immediately after a valid scan, whereas INVALIDATE_AFTER_SCAN scan mode sets the status to INACTIVE / REDEEMED. Always verify which ScanMode matches your accounting and wallet display requirements.

Learn more on our Coupons & Vouchers Overview.

Related Product & Developer Documentation

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.