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 bijPOST /api/v1/scans, ofidempotencyKeyinrequest payloadbijPOST /v1/pos/redeem). Als een terminal een verzoek opnieuw probeert wegens een netwerktime-out, retourneert Passinstance de oorspronkelijke acceptatiebon in plaats van onterecht eenALREADY_VOIDED-fout aan de kassier te tonen.
Architectuur voor eenmalige inwisseling
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
/api/v1/scans
{
"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)
{
"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:
{
"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
Apple Wallet (
.pkpass): Passinstance ondertekent een bijgewerkte pasbundel met"voided": trueinpass.jsonen het Pass Type Certificate van het sjabloon (bundleId= ApplepassTypeIdentifier), 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
Google Wallet: Passinstance roept de Google Wallet REST API aan om de
statevan het pasobject te patchen naarCOMPLETED/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) | Type | Beschrijving |
|---|---|---|
idempotencyKey | string (verplicht, max. 255) | Unieke idempotency-sleutel (aanbevolen: tenantId:terminalId:clientTxRef). |
passRef | string (verplicht, max. 500) | Gescande barcodewaarde, downloadtoken, serialNumber, of externalId / passPublicId. |
operation | PosOperation (verplicht) | Passinstance database-enum: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID of CUSTOM. Gebruik VOID of DISCOUNT voor eenmalige coupons. |
terminalId | string (optionele UUID) | UUID van de geregistreerde POS terminal (moet overeenkomen met de gekoppelde terminal indien gebonden). |
externalTerminalRef | string (optioneel) | Externe kassa-aanduiding indien u niet de Passinstance terminal-UUID gebruikt. |
amount / currency | number / string | Optioneel kortings- of transactiebedrag en ISO-4217 valutacode (bijv. EUR). |
clientTxRef | string (optioneel) | Kassabon- of winkelmandtransactiereferentie voor auditafstemming. |
metadata | object (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.
