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"etreasonCode: "OUT_OF_BALANCE"dès que le montant demandé dépassebalanceMinorsur un compte configuré avecdisallowNegativeBalance: 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
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 :
| Canal | Point d'entrée | Authentification | Cas d'usage principal | |||||
|---|---|---|---|---|---|---|---|---|
| Scanner Mobile / Web | POST /api/v1/scans | x-scanner-key | Application scanner staff configurée avec StoredValueOperation (`NONE \ | ADD \ | SUBTRACT \ | SET) et StoredValueAmountSource (FIXED \ | OPERATOR \ | MECHANIC`). |
| Lecteur NFC matériel | POST /api/v1/reader/redeem | X-Reader-Secret | Orchestration 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 POS | POST /v1/pos/redeem | Jeton Terminal POS / Bearer | Caisses enregistreuses intégrées exécutant PosOperation.DEDUCT_VALUE avec passRef (serialNumber, code-barres ou externalId) et clientTxRef. | |||||
| Rechargement Tableau de bord / Admin | POST /api/v1/passes/:id/adjust-value | JWT 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 :
/api/v1/scans
{
"scannedBarcodeValue": "PI-GFT-901244",
"scannerConfigurationId": "scfg_giftcard_debit",
"validationData": {
"amount": 24.50,
"currency": "EUR"
},
"operatorId": "emp_cashier_04"
}
Réponse (200 OK) :
{
"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) :
/api/v1/reader/redeem
{
"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) :
{
"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 :
{
"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 :
{
"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 :
| Champ | Modèle | Type | Description |
|---|---|---|---|
balanceMinor | prepaid account | Int | Solde actuel en unités monétaires mineures (ex. 7550 = 75,50 €). |
currency | prepaid account | String | Code devise ISO 4217 à 3 lettres (EUR, USD, GBP, CHF). |
disallowNegativeBalance | prepaid account | Boolean | Vaut true par défaut ; garantit balanceMinor >= 0 au niveau transactionnel en base. |
deltaMinor | prepaid ledger entry | Int | Variation entière signée (-2450 pour un débit, +5000 pour une recharge). |
balanceAfterMinor | prepaid ledger entry | Int | Instantané de balanceMinor immédiatement après l'écriture. |
idempotencyKey | prepaid ledger entry | String | Clé 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.
