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

Débit de cartes cadeaux & prépayées

Débitez les achats, rechargez les soldes, empêchez tout solde négatif et consultez l'historique des transactions.

Dans ce guide

Aperçu

Les cartes cadeaux, avoirs en magasin et portefeuilles prépayés en boucle fermée dans Passinstance s'appuient sur un grand livre immuable en partie double (modèles prepaid account et prepaid ledger entry) plutôt que sur un simple champ texte non protégé. Tous les montants monétaires sont enregistrés et calculés en unités entières mineures (balanceMinor, telles que des centimes) avec verrouillage strict au niveau ligne et invariant interdisant tout solde négatif (disallowNegativeBalance: true).

Important : Les débits sur valeur stockée échouent de manière sûre avec decision: "FAILED" et reasonCode: "OUT_OF_BALANCE" dès que le montant demandé dépasse balanceMinor sur un compte configuré avec disallowNegativeBalance: true. Ne calculez jamais les soldes côté client ; envoyez toujours la variation de transaction et laissez le registre backend valider le nouveau solde.

Architecture du registre de valeur stockée

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
DÉBIT DU REGISTRE PRÉPAYÉ & ENCAISSEMENT LECTEUR MATÉRIEL
ACTEURS SYSTÈME PARTICIPANTS
P1 Scanner / Lecteur matériel
P2 Contrôleur Scan / Reader / POS
P3 BDD prepaid account & Ledger
ÉTAPE 1a REQUÊTE / ACTION POST/api/v1/scans
›
(StoredValueOp.SUBTRACT)
ÉTAPE 1b REQUÊTE / ACTION POST/api/v1/reader/redeem
ÉTAPE 2 REQUÊTE / ACTION SELECT ... FOR UPDATE
ÉTAPE 1c REQUÊTE / ACTION POST/v1/pos/redeem
›
(Verrou ligne prepaid account)
›
(operation: DEDUCT_VALUE)
ÉTAPE 3 REQUÊTE / ACTION Vérifier disallowNegativeBalance :
›
balanceMinor >= amountMinor
ÉTAPE 4 REQUÊTE / ACTION Insérer prepaid ledger entry
›
& mettre à jour balanceMinor
ÉTAPE 5 RÉPONSE 200 OK (remainingBalance)
ÉTAPE 6 REQUÊTE / ACTION Déclencher Push APNs / Google

Points d'entrée de débit & d'ajustement des valeurs stockées

Selon l'équipement de vos points de vente ou vos besoins de gestion client, vous pouvez débiter ou recharger des soldes prépayés via quatre points d'entrée dédiés :

CanalPoint d'entréeAuthentificationCas d'usage principal
Scanner Mobile / WebPOST /api/v1/scansx-scanner-keyApplication scanner staff configurée avec StoredValueOperation (`NONE \ADD \SUBTRACT \SET) et StoredValueAmountSource (FIXED \OPERATOR \MECHANIC`).
Lecteur NFC matérielPOST /api/v1/reader/redeemX-Reader-SecretOrchestration serveur-lecteur soumettant request payload (customerId, passId, amount, idempotencyKey). (Utilisez POST /api/v1/reader/validate pour vérifier une entrée par code-barres.)
Terminal de caisse POSPOST /v1/pos/redeemJeton Terminal POS / BearerCaisses enregistreuses intégrées exécutant PosOperation.DEDUCT_VALUE avec passRef (serialNumber, code-barres ou externalId) et clientTxRef.
Rechargement Tableau de bord / AdminPOST /api/v1/passes/:id/adjust-valueJWT espace / Clé API (pass:manage)Recharges manuelles de carte cadeau (action: "CREDIT"), remboursements ou corrections administratives (action: "DEBIT").

1. Débit au scanner de comptoir (POST /api/v1/scans)

Lorsqu'une ScannerConfiguration utilise StoredValueOperation.SUBTRACT et StoredValueAmountSource.OPERATOR, le caissier saisit le total de l'achat et envoie :

POST /api/v1/scans
En-têtes
x-scanner-key sk_live_gift_register_02
x-idempotency-key scan-debit-20261116-4401
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "PI-GFT-901244",
  "scannerConfigurationId": "scfg_giftcard_debit",
  "validationData": {
    "amount": 24.50,
    "currency": "EUR"
  },
  "operatorId": "emp_cashier_04"
}

Réponse (200 OK) :

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "remainingBalance": "75.50",
  "effects": {
    "oldBalance": "100.00",
    "newBalance": "75.50",
    "transactionAmount": 24.50,
    "currency": "EUR",
    "amountBalanceBehavior": "ADD_VALUE"
  },
  "passSnapshot": {
    "id": "pass_gft_901244",
    "templateId": "tmpl_giftcard_eur",
    "serialNumber": "PI-GFT-901244",
    "externalId": "shopify_gift_901244",
    "status": "ACTIVE",
    "storedValue": "75.50"
  },
  "display": {
    "title": "€24.50 Deducted",
    "subtitle": "Remaining Balance: €75.50",
    "color": "success"
  }
}

2. Orchestration lecteur matériel (POST /api/v1/reader/redeem)

Les passerelles serveur de lecteurs sans contact et optiques s'authentifient via l'en-tête X-Reader-Secret (reader integration secret) et soumettent request payload directement à /api/v1/reader/redeem (lorsque amount est omis, le moteur exécute VALIDATE ; lorsqu'il est renseigné, il exécute DEBIT) :

POST /api/v1/reader/redeem
En-têtes
X-Reader-Secret rsec_live_reader_terminal_09a8f1
Content-Type application/json
JSON
{
  "customerId": "c1a2b3c4-d5e6-4f7a-8b9c-0123456789ab",
  "passId": "f9e8d7c6-b5a4-4321-9876-543210fedcba",
  "amount": "15.00",
  "idempotencyKey": "nfc-01:tx-883920",
  "operatorId": "nfc_gate_berlin_01"
}

Réponse (200 OK) :

JSON
{
  "success": true,
  "resultingValue": "60.50"
}

3. Intégration POS magasin (POST /v1/pos/redeem)

Les caisses enregistreuses exécutent des débits atomiques sur POST /v1/pos/redeem (monté sous /v1/pos, hors du préfixe /api/v1). passRef accepte tout jeton de passe, code-barres, serialNumber ou votre externalId métier :

JSON
{
  "idempotencyKey": "tenant_01:reg_03:tx_994812",
  "passRef": "PI-GFT-901244",
  "terminalId": "reg_03",
  "operation": "DEDUCT_VALUE",
  "amount": 15.00,
  "currency": "EUR",
  "clientTxRef": "POS-INV-2026-994812"
}

Les valeurs PosOperation prises en charge sont DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID et CUSTOM. La réponse renvoie walletPropagation (PosWalletPropagationStatus : QUEUED ou SKIPPED) lorsque les mises à jour push sont mises en file vers APNs/Google Wallet.

4. Recharges manuelles & corrections (POST /api/v1/passes/:id/adjust-value)

Pour les remboursements, crédits commerciaux ou recharges de cartes cadeaux depuis le tableau de bord ou un ERP, appelez POST /api/v1/passes/:id/adjust-value avec l'en-tête Idempotency-Key :

JSON
{
  "action": "CREDIT",
  "amount": "25.00",
  "reason": "Customer return store credit",
  "operatorId": "support_lead_02",
  "idempotencyKey": "adj-20261116-0041"
}

Les actions d'ajustement prises en charge sont CREDIT (ajouter du solde) et DEBIT (déduire du solde).

Modèle de grand livre en partie double (prepaid account & prepaid ledger entry)

Chaque passe à valeur stockée possède un enregistrement prepaid account relié à des lignes prepaid ledger entry en ajout seul :

ChampModèleTypeDescription
balanceMinorprepaid accountIntSolde actuel en unités monétaires mineures (ex. 7550 = 75,50 €).
currencyprepaid accountStringCode devise ISO 4217 à 3 lettres (EUR, USD, GBP, CHF).
disallowNegativeBalanceprepaid accountBooleanVaut true par défaut ; garantit balanceMinor >= 0 au niveau transactionnel en base.
deltaMinorprepaid ledger entryIntVariation entière signée (-2450 pour un débit, +5000 pour une recharge).
balanceAfterMinorprepaid ledger entryIntInstantané de balanceMinor immédiatement après l'écriture.
idempotencyKeyprepaid ledger entryStringClé de transaction unique empêchant tout double débit lors d'une nouvelle tentative réseau.

Pour auditer l'ensemble des débits, recharges et références opérateurs historiques, interrogez GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger ou GET /api/v1/balance-changes. Consultez également Cartes cadeaux & prépayées et Lecteurs NFC compatibles.

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.