Überblick
Digitale Geschenkkarten und aufladbare Prepaid-Karten ermöglichen es Händlern, Cafés, Gastronomiebetrieben und Einzelhandelsmarken, markeneigenes Einkaufsguthaben direkt in Apple Wallet und Google Wallet auszugeben. Kundinnen und Kunden haben ihr verfügbares Guthaben jederzeit griffbereit auf dem Smartphone, während Finanzteams über ein unveränderliches Journal mit doppelter Buchführung für den Monatsabschluss verfügen.
Backend-Architektur & Stored-Value-Entitäten
Die Guthabenfunktion in Passinstance basiert auf spezialisierten Finanzmodellen im Passinstance database-Schema:
-
Pass-Typ (pass type):
storeCard(stellt aktuelle Geldbeträge gut sichtbar in den primären Kartenfeldern dar). -
Katalog-Demo-Vorlage:
gift-card. -
Mechanik-Typ (mechanic type):
PREPAID_CARD. -
Zentrale Finanzmodelle:
- prepaid account: Führt das aktuelle Geldguthaben mit Ganzzahl-Arithmetik in kleinsten Währungseinheiten (balanceMinor) sowie dem Währungscode (currency: "EUR" | "USD"). - prepaid ledger entry: Unveränderliches Buchungsjournal, das jede Gutschrift, Abbuchung, Aufladung und Korrektur samt Zeitstempel, Bediener-ID, POS-Terminal-Referenz und Idempotenzschlüssel festhält.
Regeln der Mechanik-Engine & Buchhaltungs-Schutzmechanismen
Der Pass Mechanics Engine setzt strenge finanzielle Invarianten bei Stored-Value-Operationen durch:
-
1
Darstellung in kleinsten Währungseinheiten: Guthaben werden als Ganzzahlen in der kleinsten Währungseinheit berechnet (z. B. steht
2500für 25,00 USD und1550für 15,50 EUR). Dadurch werden Gleitkomma-Rundungsfehler auch bei hochfrequenten Einzelhandelstransaktionen vollständig ausgeschlossen. -
2
Schutz vor negativem Saldo (
disallowNegativeBalance: true): Der Server lehnt jede Abbuchungsanfrage ab, bei dercurrentBalanceMinor - debitAmountMinor < 0gilt, und antwortet mit HTTP 400 sowie dem FehlercodeINSUFFICIENT_FUNDS. -
3
Auflade-Schutz (
disableAutoRecharge: true): Verhindert automatische Aufladungen, sofern diese nicht ausdrücklich durch gespeicherte Zahlungsmethoden der Kundschaft autorisiert sind. -
4
Idempotenzschutz: Jede Abbuchungs- oder Aufladeanfrage akzeptiert einen eindeutigen
idempotencyKey. Doppelte POS-Anfragen infolge von Netzwerk-Retries geben sicher die ursprüngliche Erfolgsantwort zurück, ohne die Karte doppelt zu belasten.
Atomare POS-Einlösung & Guthabenaufladung
Kassenpersonal, integrierte POS-Hardware und Self-Checkout-Terminals kommunizieren mit der Reader-Orchestration-API oder den Kassen-Scan-Endpunkten:
HTTP-Anfrage
/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"
}
HTTP-Antwort (200 OK)
{
"success": true,
"resultingValue": "37.50"
}
Hinweis: Kassenpersonal kann Guthaben alternativ über
POST /api/v1/scans(mitx-scanner-key) oderPOST /api/v1/passes/:id/use/POST /api/v1/passes/:id/adjust-value(mit Bearer/API-Key-Auth) belasten oder aufladen und Buchungen überGET /api/v1/balance-changes?passId=<passId>prüfen. Stored-Value-Regeln unterstützenStoredValueOperation(NONE,ADD,SUBTRACT,SET) undStoredValueAmountSource(FIXED,OPERATOR,MECHANIC). Nutzen SieexternalIdbei der Erstellung, um Wallet-Karten eindeutig mit externen POS-Geschenkkartennummern zu korrelieren.
Öffentliche Selbst-Auflade-Sitzungen für Kundinnen & Kunden
Karteninhaberinnen und -inhaber können ihr Guthaben online abfragen und direkt aufladen:
-
Händler können Self-Reload-Links auf Basis von
GET /api/v1/public/reload-sessions/:tokenbereitstellen und den Zahlungsstatus überGET /api/v1/public/reload-sessions/:sessionId/statusabfragen. -
Die Reload-Sitzung integriert sich mit Stripe, PayPal, Paystack oder Mobile Money (MTN MoMo, Orange Money), um Zahlungen abzuwickeln, das
prepaid accountsofort gutzuschreiben und den aktualisierten Saldo an Apple Wallet und Google Wallet zu pushen.
Wichtig: Konfigurieren Sie im visuellen Vorlageneditor stets
changeMessage: "Neues Guthaben: %@"auf dem Guthabenfeld. Bei jeder Abbuchung oder Aufladung erscheint dann sofort eine native Sperrbildschirm-Benachrichtigung mit dem aktuellen Restguthaben auf dem Smartphone.
Entdecken Sie mehr in unserem Anwendungsfall Geschenkkarten.
