Skip to content
Guide du centre d'aide · Encaissements & transactions
3 min de lectureVérifié 2026-11-16

Validation de coupons & bons

Encaissez les bons à usage unique en caisse, invalidez les passes consommés et bloquez les doublons de scan.

Dans ce guide

Aperçu

Les coupons promotionnels et bons d'achat à usage unique exigent une validation strictement atomique afin qu'une carte ne puisse jamais être utilisée deux fois sur des caisses distinctes ni réemployée via une simple capture d'écran. En associant un modèle de coupon à une ScannerConfiguration paramétrée sur VOIDED_AFTER_SCAN scan mode, Passinstance valide le code-barres, fait passer le passe au statut VOIDED, bloque toute tentative de rejeu et déclenche immédiatement une mise à jour silencieuse qui grise la carte sur le téléphone du client.

Important : Transmettez systématiquement une clé d'idempotence lors de la validation depuis un terminal de caisse (en-tête x-idempotency-key sur POST /api/v1/scans, ou champ idempotencyKey dans request payload sur POST /v1/pos/redeem). Si une caisse réessaie après un délai réseau dépassé, Passinstance renvoie le reçu d'acceptation initial au lieu d'afficher une fausse erreur ALREADY_VOIDED au vendeur.

Architecture d'encaissement à usage unique

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
VALIDATION ATOMIQUE DE COUPON & GRISAGE WALLET
ACTEURS SYSTÈME PARTICIPANTS
P1 Appareil client
P2 Terminal Scanner / POS
P3 API Passinstance
ÉTAPE 1 REQUÊTE / ACTION Présente le code-barres
›
(PI-CPN-774109)
ÉTAPE 2 REQUÊTE / ACTION POST/api/v1/scans
›
En-tête : x-scanner-key
›
Mode : VOIDED_AFTER_SCAN
ÉTAPE 3 REQUÊTE / ACTION PassStatusRule (ACTIVE)
ÉTAPE 4 REQUÊTE / ACTION ExpirationRule (< validUntil)
ÉTAPE 5 REQUÊTE / ACTION Transaction DB atomique :
›
statusVOIDED
›
oidedAtnow()
ÉTAPE 6 RÉPONSE 200 OK
ÉTAPE 7 REQUÊTE / ACTION Envoi APNs / Google Push
ÉTAPE 8 RÉPONSE Carte grisée dans Wallet
›
(.pkpass voided: true)
ÉTAPE 9 REQUÊTE / ACTION Rejeu / capture d'écran
ÉTAPE 10 REQUÊTE / ACTION POST/api/v1/scans
ÉTAPE 11 RÉPONSE 200 OK
›
decision: "ALREADY_VOIDED"
›
reasonCode: "PASS_VOIDED_AFTER_SCAN"

Premier scan : encaissement atomique (POST /api/v1/scans)

Lorsqu'un caissier scanne un coupon actif lors du paiement, le lecteur soumet la charge utile du code-barres vers POST /api/v1/scans authentifié par x-scanner-key :

Requête HTTP

POST /api/v1/scans
En-têtes
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
  }
}

Réponse HTTP (200 OK — Accepté & invalidé)

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

Rejet d'un scan dupliqué (ALREADY_VOIDED)

Si le client tente de présenter à nouveau le même passe à une autre caisse — ou si une autre personne présente une capture d'écran transférée — PassStatusRule détecte que le passe est déjà au statut VOIDED et bloque immédiatement l'opération :

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 silencieux Wallet & grisage visuel

Immédiatement après la validation de la transition vers VOIDED :

  1. 1
    Apple Wallet (.pkpass) : Passinstance signe une nouvelle archive avec "voided": true dans pass.json grâce au certificat Pass Type du modèle (bundleId = passTypeIdentifier Apple), puis envoie une notification APNs silencieuse. iOS désature (grise) automatiquement l'apparence de la carte et désactive le code-barres dans Cartes.
  2. 2
    Google Wallet : Passinstance appelle l'API REST Google Wallet pour passer l'attribut state de l'objet à COMPLETED / EXPIRED, retirant la carte des suggestions actives et affichant un bandeau d'utilisation effectuée.

Les administrateurs et traitements serveur peuvent également invalider manuellement des coupons ou lots hors contexte de scan via POST /api/v1/passes/voiding/:id/void (request payload) ou POST /api/v1/passes/voiding/batch-void (request payload) avec un motif typé VoidingReason.

Validation depuis une caisse POS (POST /v1/pos/redeem)

Les systèmes de point de vente intégrés exécutent directement l'encaissement des bons à usage unique via POS Redemption API (POST /v1/pos/redeem et POST /v1/pos/scan — montés hors du préfixe global /api/v1) :

Champ (request payload)TypeDescription
idempotencyKeystring (obligatoire, max 255)Clé d'idempotence unique (recommandé : tenantId:terminalId:clientTxRef).
passRefstring (obligatoire, max 500)Valeur scannée, jeton de téléchargement, serialNumber, externalId ou passPublicId.
operationPosOperation (obligatoire)Énumération Passinstance database : DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID ou CUSTOM. Utilisez VOID ou DISCOUNT pour un coupon à usage unique.
terminalIdstring (UUID optionnel)UUID du POS terminal enregistré (doit correspondre au terminal lié à l'identifiant d'accès).
externalTerminalRefstring (optionnel)Code de caisse externe si vous n'utilisez pas l'UUID terminal Passinstance.
amount / currencynumber / stringMontant optionnel de la remise ou de la transaction et code devise ISO 4217 (ex. EUR).
clientTxRefstring (optionnel)Référence du ticket de caisse ou panier POS pour rapprochement d'audit.
metadataobject (optionnel)Contexte libre panier, caissier ou magasin consigné dans PosTransaction.

Après validation de POST /v1/pos/redeem, la réponse inclut walletPropagation (PosWalletPropagationStatus : QUEUED ou SKIPPED) confirmant la mise en file des actualisations Apple Wallet et Google Wallet.

Pour concevoir vos campagnes promotionnelles, consultez Coupons & bons d'achat et Modes de scan & règles de validation.

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.