Skip to content
Guide du centre d'aidePhase d'intégration 2
3 min de lectureVérifié 2026-11-16

Cartes cadeaux & prépayées

Configurez la mécanique Solde prépayé pour des cartes cadeaux rechargeables avec journal comptable auditable.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé
Éléments clés de l'interface

Sélecteur « Ajouter une mécanique » (Zoom)

Choisissez parmi 6 mécaniques intégrées : Carte à tampons, Échange de tampons, Valeur stockée, Points et paliers, Validation quotidienne ou Prolongation d'expiration.

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.

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : TRANSACTION SUR GRAND LIVRE PRÉPAYÉ
ACTEURS SYSTÈME PARTICIPANTS
P1 Lecteur POS / E-Commerce
P2 API Centrale Passinstance
P3 Base Passinstance database & Grand Livre
ÉTAPE 1 REQUÊTE / ACTION POST/api/v1/reader/redeem
ÉTAPE 2 REQUÊTE / ACTION Lire le compte
›
(Solde actuel)
ÉTAPE 3 REQUÊTE / ACTION Contrôles invariants:
›
Status === ACTIVE
›
Solde >= Débit
ÉTAPE 4 REQUÊTE / ACTION Transaction atomique
›
MàJ prepaid account
›
Insérer LedgerEntry
ÉTAPE 5 RÉPONSE 200 OK (resultingValue)
ÉTAPE 6 REQUÊTE / ACTION Push APNs silenc.
›
(Écran verrouillé Apple :
›
& PATCH REST Google
›
"Payé 12,50 €. Nouveau
›
solde : 37,50 €")

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. 1
    Représentation en sous-unités monétaires entières : les soldes sont calculés en centimes entiers (ex. 2500 représente 25,00 $ USD et 1550 représente 15,50 € EUR). Cela élimine toute erreur d'arrondi en virgule flottante lors des transactions retail à haute fréquence.
  2. 2
    Prévention des soldes négatifs (disallowNegativeBalance: true) : le serveur rejette strictement toute requête de débit lorsque currentBalanceMinor - debitAmountMinor < 0, en retournant une erreur HTTP 400 avec le code INSUFFICIENT_FUNDS.
  3. 3
    Garde-fous de rechargement (disableAutoRecharge: true) : bloque les rechargements automatiques sauf autorisation explicite via les moyens de paiement enregistrés du client.
  4. 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

POST /api/v1/reader/redeem
En-têtes
X-Reader-Secret <reader integration secret>
Content-Type application/json
JSON
{
  "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)

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

Remarque : Le personnel en caisse peut également débiter ou créditer les soldes via POST /api/v1/scans (avec x-scanner-key) ou POST /api/v1/passes/:id/use / POST /api/v1/passes/:id/adjust-value (avec authentification Bearer / clé API), et auditer les mouvements via GET /api/v1/balance-changes?passId=<passId>. Les règles de valeur stockée prennent en charge StoredValueOperation (NONE, ADD, SUBTRACT, SET) et StoredValueAmountSource (FIXED, OPERATOR, MECHANIC). Renseignez externalId à 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/:token et interroger le statut du paiement sur GET /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 account et 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.

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.