Vue d'ensemble
Les cartes cadeaux numériques et cartes prépayées à valeur stockée permettent aux commerçants, cafés, groupes hôteliers et enseignes retail d'émettre du crédit d'achat à leur marque directement dans Apple Wallet et Google Wallet. Les clients conservent toujours leur solde disponible sur leur smartphone, tandis que les équipes financières disposent d'un grand livre d'audit immuable en partie double pour les rapprochements comptables.
Architecture backend & entités de valeur stockée
La fonctionnalité de valeur stockée dans Passinstance repose sur des modèles financiers dédiés dans le schéma Passinstance database :
-
Type de passe (pass type) :
storeCard(affiche les soldes monétaires en direct bien en évidence dans les zones principales de la carte). -
Modèle de démonstration du catalogue :
gift-card. -
Type de mécanique (mechanic type) :
PREPAID_CARD. -
Modèles financiers principaux :
- prepaid account : suit le solde monétaire actif grâce à une arithmétique entière en sous-unités monétaires (balanceMinor) et aux codes de devise (currency: "EUR" | "USD"). - prepaid ledger entry : journal d'audit immuable consignant chaque crédit, débit, rechargement et ajustement avec horodatage, identifiant opérateur, référence du terminal POS et clé d'idempotence.
Règles du moteur de mécanique & garde-fous comptables
Pass Mechanics Engine impose des invariants financiers stricts sur toutes les opérations de valeur stockée :
-
1
Représentation en sous-unités monétaires entières : les soldes sont calculés en centimes entiers (ex.
2500représente 25,00 $ USD et1550représente 15,50 € EUR). Cela élimine toute erreur d'arrondi en virgule flottante lors des transactions retail à haute fréquence. -
2
Prévention des soldes négatifs (
disallowNegativeBalance: true) : le serveur rejette strictement toute requête de débit lorsquecurrentBalanceMinor - debitAmountMinor < 0, en retournant une erreur HTTP 400 avec le codeINSUFFICIENT_FUNDS. -
3
Garde-fous de rechargement (
disableAutoRecharge: true) : bloque les rechargements automatiques sauf autorisation explicite via les moyens de paiement enregistrés du client. -
4
Protection par idempotence : chaque requête de débit ou de rechargement accepte une clé unique
idempotencyKey. Les requêtes POS dupliquées dues à une nouvelle tentative réseau renvoient sans risque la réponse réussie d'origine sans débiter deux fois le client.
Encaissement POS atomique & rechargement de solde
Les caissiers, matériels POS intégrés et bornes de caisse automatique communiquent via l'API Reader Orchestration ou les endpoints de scan au comptoir :
Requête HTTP
/api/v1/reader/redeem
{
"customerId": "8f94d930-b302-4fc8-9f12-000000000001",
"passId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
"amount": "12.50",
"idempotencyKey": "pos_tx_20261115_0091",
"operatorId": "cashier_alex"
}
Réponse HTTP (200 OK)
{
"success": true,
"resultingValue": "37.50"
}
Remarque : Le personnel en caisse peut également débiter ou créditer les soldes via
POST /api/v1/scans(avecx-scanner-key) ouPOST /api/v1/passes/:id/use/POST /api/v1/passes/:id/adjust-value(avec authentification Bearer / clé API), et auditer les mouvements viaGET /api/v1/balance-changes?passId=<passId>. Les règles de valeur stockée prennent en chargeStoredValueOperation(NONE,ADD,SUBTRACT,SET) etStoredValueAmountSource(FIXED,OPERATOR,MECHANIC). RenseignezexternalIdà la création pour corréler les cartes Wallet avec les numéros de cartes cadeaux de votre caisse externe.
Sessions de rechargement en ligne par les clients
Les détenteurs de cartes peuvent consulter leur solde et ajouter du crédit d'achat en ligne :
-
Les commerçants peuvent distribuer des liens d'auto-rechargement s'appuyant sur
GET /api/v1/public/reload-sessions/:tokenet interroger le statut du paiement surGET /api/v1/public/reload-sessions/:sessionId/status. -
La session de rechargement s'intègre avec Stripe, PayPal, Paystack ou Mobile Money (MTN MoMo, Orange Money) pour encaisser le paiement, créditer instantanément le
prepaid accountet pousser le solde actualisé vers Apple Wallet et Google Wallet.
Important : Configurez toujours
changeMessage: "Nouveau solde : %@"sur le champ de solde dans l'éditeur visuel de modèles. Lors de chaque débit ou rechargement, le téléphone du client se réveille immédiatement avec une notification native sur l'écran verrouillé indiquant le nouveau solde disponible.
Découvrez davantage d'informations sur notre Cas d'usage Cartes cadeaux.
