Panoramica
I coupon e i buoni sconto digitali vivono accanto alle carte di pagamento nella schermata di blocco dello smartphone del cliente, generando tassi di riscatto nettamente superiori rispetto ai codici sconto via e-mail o ai buoni cartacei. Passinstance offre protezione crittografica, verifica antifrode monouso e annullamento in tempo reale della tessera al momento del riscatto in cassa.
Architettura backend e mappatura del tipo di pass
Nel backend di Passinstance, i programmi coupon si mappano sulle primitive ufficiali dedicate ai coupon di Apple Wallet e Google Wallet:
-
Tipo di pass (pass type):
coupon(utilizza il layout coupon nativo di Apple con un badge visivo di sconto ben visibile). -
Modello demo a catalogo:
promotional-coupon(disponibile durante l'onboarding). -
Modalità di validazione predefinita:
VOIDED_AFTER_SCAN scan mode. -
Vincoli di dominio principali:
- limitToOneActivePerPass: true: Limita gli smart link di download a un solo dispositivo, impedendo la condivisione del link di sconto in gruppi pubblici. - expirationDate: Timestamp W3C ISO 8601 che attiva automaticamente le notifiche native di scadenza sulla schermata di blocco. - addSecurityAnimation: true: Visualizza un bordo olografico dinamico attorno ai codici a barre 2D per impedire l'utilizzo fraudolento di screenshot statici.
Riscatto ed esecuzione antifrode
Il flusso di riscatto in cassa garantisce una rigorosa integrità monouso attraverso transazioni atomiche su database in Pass Mechanics Engine:
Prevenzione delle frodi da screenshot e replay
Quando l'operatore di cassa scansiona il codice a barre del coupon:
-
1
Lo scanner invia una richiesta a
POST /api/v1/scanscontenentescannedBarcodeValuee la chiave segretax-scanner-key. -
2
Il server verifica che lo stato del pass sia
ACTIVEe che il timestamp corrente precedaexpirationDate. -
3
Se valido, il database porta atomicamente lo stato del pass a
VOIDED, assegnavoidReason: "SCANNED_AT_CHECKOUT"e registra la transazione di scansione. -
4
Se un operatore o un utente malintenzionato scansiona nuovamente lo stesso codice a barre, il motore di validazione rifiuta immediatamente la transazione con codice decisione
ALREADY_VOIDEDe messaggio di errorePASS_VOIDED_AFTER_SCAN. -
5
Contestualmente, Passinstance accoda una notifica push in background verso Apple APNs e Google Wallet. La tessera sullo smartphone del cliente si oscura immediatamente mostrando l'etichetta "Redeemed" (o stato riscattato), impedendone il riutilizzo a un'altra cassa.
DTO concreti di richiesta e risposta della scansione
Sistemi POS, terminali scanner e casse e-commerce interagiscono con l'endpoint di validazione nel seguente formato:
Richiesta HTTP
/api/v1/scans
{
"scannedBarcodeValue": "PI-CPN-849201",
"operatorId": "emp_sarah_m"
}
Risposta HTTP (200 OK)
{
"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"
}
}
}
Misure di sicurezza per la distribuzione delle campagne
Nella distribuzione di coupon tramite pagine PassFlow pubbliche, creazione via API o campagne SMS:
-
Scadenza del download (
enableDownloadUntil): Imposti data e ora rigorose ("YYYY-MM-DD HH:mm"o timestamp ISO surequest payload/ configurazione del modello) oltre le quali i link di download non ancora riscattati restituiscono HTTP 410 Gone. -
Protezione con PIN di accesso: Protegga i link promozionali ad alto valore con un PIN di accesso (
?pin=oppureX-Wallet-Experience-Pin) consegnato via SMS o ricevuta d'acquisto. -
Correlazione CRM ed e-commerce (
externalId): Passi unexternalId(es.order_88412_cpn) suPOST /api/v1/passeso/api/v1/passes/upsert-by-external-idcosì da riconciliare con precisione i riscatti dei buoni monouso nel sistema ordini. -
Associazione del link a un solo dispositivo: Abiliti
limitToOneActivePerPassin modo che il link serializzato di ogni cliente si blocchi sul primo dispositivo registrato anziché circolare nei gruppi pubblici.
Importante:
VOIDED_AFTER_SCAN scan modeannulla immediatamente il pass dopo una scansione valida, mentreINVALIDATE_AFTER_SCAN scan modeimposta lo stato suINACTIVE/REDEEMED. Verifichi sempre qualeScanModecorrisponde alle proprie esigenze contabili e di visualizzazione nel Wallet.
Approfondisca nella Panoramica Coupon e buoni sconto.
