Skip to content
Help Center Guide · Redemption & Transactions
3 min readVerified 2026-11-16

Coupon & Voucher Redemption

Process single-use voucher redemptions at point of sale, void spent passes automatically, and block duplicate scans.

In This Guide

Overview

Single-use promotional coupons and vouchers require strict atomic validation so that a pass can never be redeemed twice across different registers or shared via static screenshots. By pairing a coupon template with a ScannerConfiguration set to VOIDED_AFTER_SCAN scan mode, Passinstance validates the barcode, transitions the pass to VOIDED, blocks replay attempts, and triggers an immediate silent wallet update to grey out the pass on the customer's device.

Important: Always include an idempotency key when submitting redemptions from POS terminals (x-idempotency-key header on POST /api/v1/scans, or idempotencyKey in request payload on POST /v1/pos/redeem). If a terminal retries due to a network timeout, Passinstance returns the original acceptance receipt rather than throwing a false ALREADY_VOIDED error to the cashier.

Single-Use Redemption Architecture

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
ATOMIC COUPON REDEMPTION & WALLET GREY-OUT
PARTICIPATING SYSTEM ACTORS
P1 Customer Device
P2 Scanner / POS Terminal
P3 Passinstance API
STEP 1 REQUEST / ACTION Present Coupon Barcode
›
(PI-CPN-774109)
STEP 2 REQUEST / ACTION POST/api/v1/scans
›
Header: x-scanner-key
›
Mode: VOIDED_AFTER_SCAN
STEP 3 REQUEST / ACTION PassStatusRule (ACTIVE)
STEP 4 REQUEST / ACTION ExpirationRule (< validUntil)
STEP 5 REQUEST / ACTION Atomic DB Transaction:
›
statusVOIDED
›
oidedAtnow()
STEP 6 RESPONSE 200 OK
STEP 7 REQUEST / ACTION Dispatch APNs / Google Push
STEP 8 RESPONSE Wallet Card Greyed Out
›
(Apple voided: true .pkpass)
STEP 9 REQUEST / ACTION Replay / Screenshot Scan
STEP 10 REQUEST / ACTION POST/api/v1/scans
STEP 11 RESPONSE 200 OK
›
decision: "ALREADY_VOIDED"
›
reasonCode: "PASS_VOIDED_AFTER_SCAN"

First Scan: Atomic Redemption (POST /api/v1/scans)

When a cashier scans an active coupon at checkout, the scanner submits the barcode payload to POST /api/v1/scans authenticated by x-scanner-key:

HTTP Request

POST /api/v1/scans
Headers
x-scanner-key sk_live_pos_register_01
x-idempotency-key pos-tx-20261116-99481
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "PI-CPN-774109",
  "scannerConfigurationId": "scfg_coupon_checkout",
  "operatorId": "cashier_12",
  "terminalId": "reg_berlin_01",
  "validationData": {
    "receiptNumber": "RCPT-2026-88412",
    "basketTotal": 64.00
  }
}

HTTP Response (200 OK — Accepted & Voided)

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "reasonCode": "PASS_VOIDED_AFTER_SCAN",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true },
    { "rule": "ExpirationRule", "passed": true },
    { "rule": "DefaultAcceptanceRule", "passed": true }
  ],
  "passSnapshot": {
    "id": "pass_cpn_774109",
    "templateId": "tmpl_winter_promo_25",
    "serialNumber": "PI-CPN-774109",
    "externalId": "promo_order_774109",
    "status": "VOIDED",
    "expirationDate": "2026-12-31T23:59:59.000Z",
    "attributes": {
      "offerTitle": "25% Off Winter Collection",
      "promoCode": "WINTER25"
    }
  },
  "display": {
    "title": "Coupon Redeemed",
    "subtitle": "Apply 25% discount — Pass is now voided",
    "color": "success"
  }
}

Duplicate Scan Rejection (ALREADY_VOIDED)

If the customer attempts to scan the same pass again at another register — or if a second person presents a forwarded screenshot of the barcode — PassStatusRule detects that the pass is already VOIDED and immediately halts execution:

JSON
{
  "decision": "ALREADY_VOIDED",
  "status": "REJECTED",
  "reasonCode": "PASS_VOIDED_AFTER_SCAN",
  "ruleTrace": [
    {
      "rule": "PassStatusRule",
      "passed": false,
      "reasonCode": "PASS_VOIDED_AFTER_SCAN"
    }
  ],
  "passSnapshot": {
    "id": "pass_cpn_774109",
    "templateId": "tmpl_winter_promo_25",
    "serialNumber": "PI-CPN-774109",
    "externalId": "promo_order_774109",
    "status": "VOIDED"
  },
  "display": {
    "title": "Already Redeemed",
    "subtitle": "This voucher was already used and is void.",
    "color": "error"
  }
}

Silent Wallet Push & Visual Grey-Out

Immediately after committing the VOIDED state transition:

  1. 1
    Apple Wallet (.pkpass): Passinstance signs an updated pass bundle with "voided": true in pass.json and the template's Pass Type Certificate (bundleId = Apple passTypeIdentifier), then dispatches a silent APNs push notification. iOS automatically desaturates (greys out) the pass face and invalidates the barcode in Apple Wallet.
  2. 2
    Google Wallet: Passinstance invokes the Google Wallet REST API to patch the pass object's state to COMPLETED / EXPIRED, removing it from active lock-screen suggestions and displaying a redeemed status banner.

Administrators and backend workers can also manually void individual coupons or batches outside a scan flow via POST /api/v1/passes/voiding/:id/void (request payload) or POST /api/v1/passes/voiding/batch-void (request payload) with a typed VoidingReason.

Retail POS Terminal Redemption (POST /v1/pos/redeem)

Integrated retail point-of-sale systems execute direct single-use voucher redemptions via POS Redemption API (POST /v1/pos/redeem and POST /v1/pos/scan — excluded from the global /api/v1 prefix):

Field (request payload)TypeDescription
idempotencyKeystring (required, max 255)Unique idempotency key (recommended: tenantId:terminalId:clientTxRef).
passRefstring (required, max 500)Scanned barcode value, download token, serialNumber, or externalId / passPublicId.
operationPosOperation (required)supported enum: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, or CUSTOM. Use VOID or DISCOUNT for single-use coupons.
terminalIdstring (optional UUID)UUID of the registered POS terminal (must match credential terminal if bound).
externalTerminalRefstring (optional)External register code if not using the Passinstance terminal UUID.
amount / currencynumber / stringOptional discount or transaction amount and ISO-4217 currency code (e.g. EUR).
clientTxRefstring (optional)POS receipt or basket transaction reference for audit reconciliation.
metadataobject (optional)Opaque basket, cashier, or store context recorded in PosTransaction.

After committing POST /v1/pos/redeem, the response includes walletPropagation (PosWalletPropagationStatus: QUEUED or SKIPPED) confirming push propagation to Apple Wallet and Google Wallet.

For campaign design best practices, see Coupons & Vouchers and Scan Modes & Validation Rules.

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.