Skip to content
Helpcentrum-gids
3 min leestijdGecontroleerd 2026-11-16

Kortingsbonnen & vouchers

Lanceer eenmalige of tijdelijke promoties met scanvalidatie en automatische vervaldatum na inwisseling.

In deze gids

Overzicht

Digitale kortingsbonnen en vouchers in een wallet staan direct naast betaalkaarten op het toegangsscherm van de smartphone van een klant, wat zorgt voor aanzienlijk hogere inwisselpercentages dan kortingscodes per e-mail of papieren bonnen. Passinstance biedt cryptografische bescherming, fraudebestendige eenmalige verificatie en directe ongeldigmaking van de pas bij inwisseling aan de kassa.

Backendarchitectuur & pastypetoewijzing

In de Passinstance-backend worden kortingsbonprogramma's gekoppeld aan de officiële kortingsbonprimitieven van Apple Wallet en Google Wallet:

  • Pastype (pass type): coupon (gebruikt de native Apple-kortingsbonlay-out met een opvallend visueel kortingslabel).
  • Demoblauwdruk in catalogus: promotional-coupon (beschikbaar tijdens onboarding).
  • Standaard validatiemodus: VOIDED_AFTER_SCAN scan mode.
  • Belangrijkste domeinbeperkingen:

- limitToOneActivePerPass: true: Beperkt slimme downloadlinks tot één apparaat, zodat kortingslinks niet in groepen kunnen worden gedeeld. - expirationDate: W3C ISO 8601-tijdstempel dat automatisch native vervalmeldingen op het toegangsscherm activeert. - addSecurityAnimation: true: Toont een dynamische holografische rand rond 2D-barcodes om fraude met statische screenshots te voorkomen.

Inwisseling & fraudebestrijding tijdens uitvoering

De inwisselingsworkflow aan de kassa dwingt strikte eenmalige geldigheid af via atomaire databasetransacties in Pass Mechanics Engine:

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
INWISSELING & ONGELDIGMAKING VAN KORTINGSBON
DEELNEMENDE SYSTEEMACTOREN
P1 Klant Wallet-pas
P2 Scanner / Kassaterminal
P3 Passinstance Core API
STAP 1 VERZOEK / ACTIE Toon barcode-QR
›
(PI-CPN-849201)
STAP 2 VERZOEK / ACTIE POST/api/v1/scans
›
Header: x-scanner-key
›
Body: {scannedBarcodeVal}
STAP 3 VERZOEK / ACTIE Controleer status === ACTIVE
STAP 4 VERZOEK / ACTIE Check expirationDate >= now()
STAP 5 VERZOEK / ACTIE Atomaire update:
›
status = VOIDED,
›
oidedAt = now()
STAP 6 ANTWOORD 200 OK
STAP 7 VERZOEK / ACTIE APNs-push & Google PATCH
›
{ decision: "SUCCESS",
›
(Stille update naar toestel)
STAP 8 ANTWOORD Pas wordt grijs & VOIDED ====== status: "ACCEPTED" }

Voorkomen van screenshot- en herhalingsfraude

Wanneer een kassamedewerker de barcode van de kortingsbon scant:

  1. 1
    De scanner stuurt een verzoek naar POST /api/v1/scans met scannedBarcodeValue en de geheime x-scanner-key van de scanner.
  2. 2
    De server bevestigt dat de passtatus ACTIVE is en dat het huidige tijdstip vóór expirationDate ligt.
  3. 3
    Indien geldig, zet de database de passtatus atomair om naar VOIDED, kent voidReason: "SCANNED_AT_CHECKOUT" toe en legt de scantransactie vast.
  4. 4
    Als een medewerker of kwaadwillende dezelfde barcode nogmaals scant, weigert de validatie-engine de transactie direct met beslissingscode ALREADY_VOIDED en foutmelding PASS_VOIDED_AFTER_SCAN.
  5. 5
    Tegelijkertijd plaatst Passinstance een achtergrondpushmelding voor Apple APNs en Google Wallet in de wachtrij. De pas op de telefoon van de klant wordt onmiddellijk grijs met een duidelijk watermerk "Ingewisseld" ("Redeemed"), waardoor hergebruik aan een andere kassa wordt geblokkeerd.

Concrete scanverzoek- & respons-DTO's

Kassasystemen, scannerterminals en e-commerce check-outs communiceren met het validatie-endpoint:

HTTP-verzoek

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

Beveiligingsmaatregelen voor campagnedistributie

Bij het verspreiden van kortingsbonnen via openbare PassFlow-pagina's, API-aanmaak of sms-campagnes:

  • Downloadvervaldatum (enableDownloadUntil): Stel een strikte datum-tijd in ("YYYY-MM-DD HH:mm" of ISO-tijdstempel in request payload / sjabloonconfiguratie) waarna niet-geclaimde downloadlinks HTTP 410 Gone retourneren.
  • Toegangs-PIN-beveiliging: Beveilig waardevolle promotielinks met een toegangs-PIN (?pin= of X-Wallet-Experience-Pin) die per sms of aankoopbon wordt meegestuurd.
  • CRM- & e-commercecorrelatie (externalId): Geef een externalId (bijv. order_88412_cpn) mee op POST /api/v1/passes of /api/v1/passes/upsert-by-external-id zodat inwisselingen van eenmalige vouchers netjes kunnen worden verwerkt in uw ordersysteem.
  • Koppeling aan één apparaat: Schakel limitToOneActivePerPass in zodat de geserialiseerde downloadlink van elke klant zich vergrendelt aan het eerst geregistreerde apparaat in plaats van vrij rond te gaan in openbare groepen.

Belangrijk: VOIDED_AFTER_SCAN scan mode maakt de pas onmiddellijk ongeldig (VOIDED) na een geldige scan, terwijl INVALIDATE_AFTER_SCAN scan mode de status op INACTIVE / REDEEMED zet. Controleer altijd welke ScanMode aansluit bij uw boekhoudkundige en wallet-weergavevereisten.

Lees meer in ons Overzicht van kortingsbonnen & vouchers.

Gerelateerde product- en ontwikkelaarsdocs

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.