Skip to content
Helpcentrum-gids · Inwisseling & transacties
3 min leestijdGecontroleerd 2026-11-16

Coupons & vouchers inwisselen

Verwerk eenmalige kortingsbonnen aan de kassa, trek verbruikte kaarten automatisch in en voorkom dubbele scans.

In deze gids

Overzicht

Eenmalige promotiecoupons en vouchers vereisen strikte atomaire validatie, zodat een pas nooit twee keer kan worden ingewisseld bij verschillende kassa's of kan worden gedeeld via statische screenshots. Door een couponsjabloon te koppelen aan een ScannerConfiguration ingesteld op VOIDED_AFTER_SCAN scan mode, valideert Passinstance de barcode, zet het de pas over op VOIDED, blokkeert het herhalingspogingen en activeert het direct een stille walletupdate om de pas op het apparaat van de klant grijs te maken.

Belangrijk: Stuur altijd een idempotency-sleutel mee wanneer u inwisselingen verstuurt vanaf POS-terminals (x-idempotency-key-header bij POST /api/v1/scans, of idempotencyKey in request payload bij POST /v1/pos/redeem). Als een terminal een verzoek opnieuw probeert wegens een netwerktime-out, retourneert Passinstance de oorspronkelijke acceptatiebon in plaats van onterecht een ALREADY_VOIDED-fout aan de kassier te tonen.

Architectuur voor eenmalige inwisseling

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
ATOMAIRE COUPONINWISSELING & GRIJS MAKEN IN WALLET
DEELNEMENDE SYSTEEMACTOREN
P1 Apparaat van klant
P2 Scanner / POS-terminal
P3 Passinstance API
STAP 1 VERZOEK / ACTIE Toon couponbarcode
›
(PI-CPN-774109)
STAP 2 VERZOEK / ACTIE POST/api/v1/scans
›
Header: x-scanner-key
›
Mode: VOIDED_AFTER_SCAN
STAP 3 VERZOEK / ACTIE PassStatusRule (ACTIVE)
STAP 4 VERZOEK / ACTIE ExpirationRule (< validUntil)
STAP 5 VERZOEK / ACTIE Atomaire DB-transactie:
›
statusVOIDED
›
oidedAtnow()
STAP 6 ANTWOORD 200 OK
STAP 7 VERZOEK / ACTIE Verstuur APNs / Google Push
STAP 8 ANTWOORD Walletkaart uitgegrijsd
›
(Apple voided: true .pkpass)
STAP 9 VERZOEK / ACTIE Herhaal- / screenshotscan
STAP 10 VERZOEK / ACTIE POST/api/v1/scans
STAP 11 ANTWOORD 200 OK
›
decision: "ALREADY_VOIDED"
›
reasonCode: "PASS_VOIDED_AFTER_SCAN"

Eerste scan: atomaire inwisseling (POST /api/v1/scans)

Wanneer een kassier bij het afrekenen een actieve coupon scant, verstuurt de scanner de barcodepayload naar POST /api/v1/scans, geauthenticeerd met x-scanner-key:

HTTP-verzoek

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-antwoord (200 OK — geaccepteerd & ongeldig gemaakt)

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"
  }
}

Weigering van dubbele scans (ALREADY_VOIDED)

Als de klant dezelfde pas opnieuw probeert te scannen bij een andere kassa — of als een tweede persoon een doorgestuurd screenshot van de barcode toont — detecteert PassStatusRule dat de pas al VOIDED is en breekt de uitvoering direct af:

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"
  }
}

Stille wallet-push & visueel grijs maken

Direct na het vastleggen van de statusovergang naar VOIDED:

  1. 1
    Apple Wallet (.pkpass): Passinstance ondertekent een bijgewerkte pasbundel met "voided": true in pass.json en het Pass Type Certificate van het sjabloon (bundleId = Apple passTypeIdentifier), en verzendt vervolgens een stille APNs-pushmelding. iOS ontzadigt (maakt grijs) automatisch de voorzijde van de pas en maakt de barcode in Apple Wallet ongeldig.
  2. 2
    Google Wallet: Passinstance roept de Google Wallet REST API aan om de state van het pasobject te patchen naar COMPLETED / EXPIRED, waardoor deze verdwijnt uit actieve vergrendelschermsuggesties en een banner met de ingewisselde status wordt getoond.

Beheerders en backendworkers kunnen individuele coupons of batches ook handmatig buiten een scanstroom ongeldig maken via POST /api/v1/passes/voiding/:id/void (request payload) of POST /api/v1/passes/voiding/batch-void (request payload) met een getypeerde VoidingReason.

Inwisseling via retail POS-terminals (POST /v1/pos/redeem)

Geïntegreerde retailkassasystemen voeren directe eenmalige voucherinwisselingen uit via POS Redemption API (POST /v1/pos/redeem en POST /v1/pos/scan — uitgesloten van het algemene /api/v1-voorvoegsel):

Veld (request payload)TypeBeschrijving
idempotencyKeystring (verplicht, max. 255)Unieke idempotency-sleutel (aanbevolen: tenantId:terminalId:clientTxRef).
passRefstring (verplicht, max. 500)Gescande barcodewaarde, downloadtoken, serialNumber, of externalId / passPublicId.
operationPosOperation (verplicht)Passinstance database-enum: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID of CUSTOM. Gebruik VOID of DISCOUNT voor eenmalige coupons.
terminalIdstring (optionele UUID)UUID van de geregistreerde POS terminal (moet overeenkomen met de gekoppelde terminal indien gebonden).
externalTerminalRefstring (optioneel)Externe kassa-aanduiding indien u niet de Passinstance terminal-UUID gebruikt.
amount / currencynumber / stringOptioneel kortings- of transactiebedrag en ISO-4217 valutacode (bijv. EUR).
clientTxRefstring (optioneel)Kassabon- of winkelmandtransactiereferentie voor auditafstemming.
metadataobject (optioneel)Vrije winkelmand-, kassier- of winkelcontext opgeslagen in PosTransaction.

Na het verwerken van POST /v1/pos/redeem bevat het antwoord walletPropagation (PosWalletPropagationStatus: QUEUED of SKIPPED) ter bevestiging van de pushverspreiding naar Apple Wallet en Google Wallet.

Raadpleeg voor best practices bij het ontwerpen van campagnes Coupons & vouchers en Scanmodi & validatieregels.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.