Skip to content
Guida del Centro assistenza · Riscatti e transazioni
3 min di letturaVerificato 2026-11-16

Riscatto coupon e voucher

Convalida buoni monouso in cassa, annulla automaticamente i pass usati e blocca le doppie scansioni.

In questa guida

Panoramica

Coupon promozionali e voucher monouso richiedono una validazione atomica rigorosa affinché un pass non possa mai essere riscattato due volte presso casse diverse o condiviso tramite screenshot statici. Associando un modello di coupon a una ScannerConfiguration impostata su VOIDED_AFTER_SCAN scan mode, Passinstance convalida il codice a barre, porta il pass allo stato VOIDED, blocca i tentativi di riutilizzo e attiva immediatamente un aggiornamento silenzioso del Wallet per oscurare (rendere grigio) il pass sul dispositivo del cliente.

Importante: Includa sempre una chiave di idempotenza quando si inviano riscatti dai terminali POS (header x-idempotency-key su POST /api/v1/scans oppure idempotencyKey in request payload su POST /v1/pos/redeem). Se un terminale riprova dopo un timeout di rete, Passinstance restituisce la ricevuta di accettazione originale invece di generare un falso errore ALREADY_VOIDED al cassiere.

Architettura del riscatto monouso

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
RISCATTO ATOMICO DEL COUPON E OSCURAMENTO NEL WALLET
ATTORI DI SISTEMA COINVOLTI
P1 Dispositivo cliente
P2 Scanner / Terminale POS
P3 API Passinstance
FASE 1 RICHIESTA / AZIONE Mostra codice coupon
›
(PI-CPN-774109)
FASE 2 RICHIESTA / AZIONE POST/api/v1/scans
›
Header: x-scanner-key
›
Mode: VOIDED_AFTER_SCAN
FASE 3 RICHIESTA / AZIONE PassStatusRule (ACTIVE)
FASE 4 RICHIESTA / AZIONE ExpirationRule (< validUntil)
FASE 5 RICHIESTA / AZIONE Transazione DB atomica:
›
statusVOIDED
›
oidedAtnow()
FASE 6 RISPOSTA 200 OK
FASE 7 RICHIESTA / AZIONE Invio APNs / Google Push
FASE 8 RISPOSTA Pass Wallet oscurato
›
(Apple voided: true .pkpass)
FASE 9 RICHIESTA / AZIONE Scansione replay/screenshot
FASE 10 RICHIESTA / AZIONE POST/api/v1/scans
FASE 11 RISPOSTA 200 OK
›
decision: "ALREADY_VOIDED"
›
reasonCode: "PASS_VOIDED_AFTER_SCAN"

Prima scansione: riscatto atomico (POST /api/v1/scans)

Quando un cassiere scansiona un coupon attivo alla cassa, lo scanner invia il payload del codice a barre a POST /api/v1/scans autenticato con x-scanner-key:

Richiesta HTTP

POST /api/v1/scans
Header
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
  }
}

Risposta HTTP (200 OK — Accettato e annullato)

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

Rifiuto delle scansioni duplicate (ALREADY_VOIDED)

Se il cliente prova a scansionare nuovamente lo stesso pass presso un'altra cassa — oppure se una seconda persona presenta uno screenshot inoltrato del codice a barre — PassStatusRule rileva che il pass è già VOIDED e interrompe immediatamente l'esecuzione:

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

Push silenziosa al Wallet e oscuramento visivo

Subito dopo il commit della transizione di stato VOIDED:

  1. 1
    Apple Wallet (.pkpass): Passinstance firma un bundle del pass aggiornato con "voided": true in pass.json e il Pass Type Certificate del modello (bundleId = Apple passTypeIdentifier), poi invia una notifica push silenziosa APNs. iOS desatura automaticamente (rende grigio) il fronte del pass e invalida il codice a barre in Apple Wallet.
  2. 2
    Google Wallet: Passinstance richiama la REST API di Google Wallet per aggiornare lo stato state dell'oggetto pass a COMPLETED / EXPIRED, rimuovendolo dai suggerimenti attivi sulla schermata di blocco e mostrando un banner di stato riscattato.

Gli amministratori e i worker backend possono anche annullare manualmente singoli coupon o batch al di fuori di un flusso di scansione tramite POST /api/v1/passes/voiding/:id/void (request payload) o POST /api/v1/passes/voiding/batch-void (request payload) indicando un VoidingReason tipizzato.

Riscatto da terminale POS retail (POST /v1/pos/redeem)

I sistemi point-of-sale retail integrati eseguono riscatti diretti di voucher monouso tramite POS Redemption API (POST /v1/pos/redeem e POST /v1/pos/scan — esclusi dal prefisso globale /api/v1):

Campo (request payload)TipoDescrizione
idempotencyKeystring (obbligatorio, max 255)Chiave di idempotenza univoca (consigliata: tenantId:terminalId:clientTxRef).
passRefstring (obbligatorio, max 500)Valore del codice a barre scansionato, token di download, serialNumber oppure externalId / passPublicId.
operationPosOperation (obbligatorio)Enum Passinstance database: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID o CUSTOM. Utilizzi VOID o DISCOUNT per coupon monouso.
terminalIdstring (UUID opzionale)UUID del POS terminal registrato (deve corrispondere al terminale della credenziale se vincolato).
externalTerminalRefstring (opzionale)Codice esterno della cassa se non si utilizza l'UUID del terminale Passinstance.
amount / currencynumber / stringImporto opzionale di sconto o transazione e codice valuta ISO-4217 (es. EUR).
clientTxRefstring (opzionale)Riferimento scontrino POS o transazione carrello per la riconciliazione di audit.
metadataobject (opzionale)Contesto opaco di carrello, cassiere o punto vendita registrato in PosTransaction.

Dopo il commit di POST /v1/pos/redeem, la risposta include walletPropagation (PosWalletPropagationStatus: QUEUED o SKIPPED) a conferma dell'accodamento degli aggiornamenti push verso Apple Wallet e Google Wallet.

Per le best practice di progettazione delle campagne, consulti Coupon e voucher e Modalità di scansione e regole di validazione.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.