Vue d'ensemble
Les coupons et bons d'achat dans un portefeuille numérique s'affichent aux côtés des cartes bancaires sur l'écran verrouillé du smartphone du client, générant des taux d'utilisation nettement supérieurs aux codes promo envoyés par e-mail ou aux coupons papier. Passinstance assure une protection cryptographique, une vérification anti-fraude à usage unique et l'invalidation en temps réel de la carte dès son encaissement en caisse.
Architecture backend & correspondance des types de passes
Dans le backend Passinstance, les campagnes de coupons s'appuient sur les primitives officielles Apple Wallet et Google Wallet :
-
Type de passe (pass type) :
coupon(utilise la mise en page native Apple Coupon avec un badge promotionnel bien visible). -
Modèle de démonstration du catalogue :
promotional-coupon(disponible pendant l'onboarding). -
Mode de validation par défaut :
VOIDED_AFTER_SCAN scan mode. -
Contraintes métier principales :
- limitToOneActivePerPass: true : restreint les liens de téléchargement intelligents à un seul appareil, empêchant le partage d'un même lien de réduction au sein d'un groupe. - expirationDate : horodatage ISO 8601 W3C déclenchant automatiquement les notifications natives d'expiration sur l'écran verrouillé. - addSecurityAnimation: true : affiche une bordure holographique dynamique autour des codes-barres 2D afin de bloquer la présentation frauduleuse de captures d'écran statiques.
Encaissement & exécution anti-fraude
Le workflow d'encaissement en caisse garantit une intégrité stricte à usage unique grâce aux transactions atomiques de Pass Mechanics Engine :
Prévenir la fraude par capture d'écran et rejeu
Lorsqu'un caissier scanne le code-barres du coupon :
-
1
Le scanner envoie une requête vers
POST /api/v1/scanscontenantscannedBarcodeValueet la clé secrètex-scanner-key. -
2
Le serveur vérifie que le statut du passe est
ACTIVEet que l'heure courante précèdeexpirationDate. -
3
Si le coupon est valide, la base de données bascule atomiquement le statut du passe sur
VOIDED, attribuevoidReason: "SCANNED_AT_CHECKOUT"et consigne la transaction de scan. -
4
Si un opérateur ou une personne malveillante tente de scanner à nouveau le même code-barres, le moteur de validation rejette immédiatement la transaction avec le code de décision
ALREADY_VOIDEDet le message d'erreurPASS_VOIDED_AFTER_SCAN. -
5
Simultanément, Passinstance met en file d'attente une notification push en arrière-plan vers Apple APNs et Google Wallet. La carte sur le téléphone du client se grise instantanément avec un filigrane visible « Redeemed » (Utilisé), empêchant toute réutilisation à une autre caisse.
Exemples concrets de requête et réponse DTO de scan
Les logiciels de caisse, terminaux scanner et tunnels e-commerce communiquent avec l'endpoint de validation :
Requête HTTP
/api/v1/scans
{
"scannedBarcodeValue": "PI-CPN-849201",
"operatorId": "emp_sarah_m"
}
Réponse 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"
}
}
}
Garde-fous de distribution des campagnes
Lorsque vous diffusez des coupons via des pages publiques, la création par API ou des campagnes SMS :
-
Expiration du téléchargement (
enableDownloadUntil) : fixez une date et heure limite ("YYYY-MM-DD HH:mm"ou horodatage ISO surrequest payload/ configuration du modèle) après laquelle les liens non réclamés renvoient un code HTTP 410 Gone. -
Protection par code PIN d'accès : protégez les liens promotionnels à forte valeur par un code PIN (
?pin=ouX-Wallet-Experience-Pin) envoyé par SMS ou sur le reçu d'achat. -
Corrélation CRM & e-commerce (
externalId) : transmettez unexternalId(ex.order_88412_cpn) surPOST /api/v1/passesou/api/v1/passes/upsert-by-external-idafin de rapprocher proprement chaque utilisation de bon dans votre système de commandes. -
Liaison stricte à un seul appareil : activez
limitToOneActivePerPasspour que le lien sérialisé de chaque client se verrouille sur le premier appareil enregistré au lieu de circuler dans des groupes publics.
Important :
VOIDED_AFTER_SCAN scan modeannule le passe immédiatement après un scan valide, tandis queINVALIDATE_AFTER_SCAN scan modepositionne son statut surINACTIVE/REDEEMED. Vérifiez toujours quelScanModecorrespond à vos exigences comptables et d'affichage dans le Wallet.
Pour en savoir plus, consultez notre Présentation Coupons & bons d'achat.
