Skip to content
Guide du centre d'aide
4 min de lectureVérifié 2026-11-16

Coupons & bons d'achat

Lancez des offres promotionnelles à usage unique ou limité avec validation au scan et expiration après usage.

Dans ce guide

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 :

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : ENCAISSEMENT & ANNULATION DE COUPON
ACTEURS SYSTÈME PARTICIPANTS
P1 Passe Wallet Client
P2 Scanner / Terminal POS
P3 API Centrale Passinstance
ÉTAPE 1 REQUÊTE / ACTION Présenter QR code-barres
›
(PI-CPN-849201)
ÉTAPE 2 REQUÊTE / ACTION POST/api/v1/scans
›
En-tête : x-scanner-key
›
Corps : {scannedBarcodeVal}
ÉTAPE 3 REQUÊTE / ACTION Vérifier status === ACTIVE
ÉTAPE 4 REQUÊTE / ACTION Vérifier expirationDate >= now()
ÉTAPE 5 REQUÊTE / ACTION Mise à jour atomique :
›
status = VOIDED,
›
oidedAt = now()
ÉTAPE 6 RÉPONSE 200 OK
ÉTAPE 7 REQUÊTE / ACTION Push APNs & PATCH Google
›
{ decision: "SUCCESS",
›
(MàJ silencieuse appareil)
ÉTAPE 8 RÉPONSE Carte grisée & annulée ======== status: "ACCEPTED" }

Prévenir la fraude par capture d'écran et rejeu

Lorsqu'un caissier scanne le code-barres du coupon :

  1. 1
    Le scanner envoie une requête vers POST /api/v1/scans contenant scannedBarcodeValue et la clé secrète x-scanner-key.
  2. 2
    Le serveur vérifie que le statut du passe est ACTIVE et que l'heure courante précède expirationDate.
  3. 3
    Si le coupon est valide, la base de données bascule atomiquement le statut du passe sur VOIDED, attribue voidReason: "SCANNED_AT_CHECKOUT" et consigne la transaction de scan.
  4. 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_VOIDED et le message d'erreur PASS_VOIDED_AFTER_SCAN.
  5. 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

POST /api/v1/scans
En-têtes
x-scanner-key sk_live_counter_register_04
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "PI-CPN-849201",
  "operatorId": "emp_sarah_m"
}

Réponse HTTP (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"
    }
  }
}

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 sur request 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= ou X-Wallet-Experience-Pin) envoyé par SMS ou sur le reçu d'achat.
  • Corrélation CRM & e-commerce (externalId) : transmettez un externalId (ex. order_88412_cpn) sur POST /api/v1/passes ou /api/v1/passes/upsert-by-external-id afin de rapprocher proprement chaque utilisation de bon dans votre système de commandes.
  • Liaison stricte à un seul appareil : activez limitToOneActivePerPass pour 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 mode annule le passe immédiatement après un scan valide, tandis que INVALIDATE_AFTER_SCAN scan mode positionne son statut sur INACTIVE / REDEEMED. Vérifiez toujours quel ScanMode correspond à vos exigences comptables et d'affichage dans le Wallet.

Pour en savoir plus, consultez notre Présentation Coupons & bons d'achat.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.