Skip to content
Hilfecenter-AnleitungOnboarding-Phase 2
3 Min. LesezeitGeprüft 2026-11-16

Geschenkkarten & Prepaid-Guthaben

Konfigurieren Sie Stored-Value-Mechaniken für aufladbare Wallet-Geschenkkarten mit prüfbaren Buchungssalden.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Auswahl „Add a Pass Mechanic“ (Zoom)

Wählen Sie aus 6 integrierten Mechaniken: Stempelkarte, Stempel-Einlösung, Guthaben (Stored Value), Punkte & Stufen, Einmal-pro-Tag-Validierung oder Laufzeitverlängerung.

Ü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.

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
STORED-VALUE-BUCHUNGSTRANSAKTION
BETEILIGTE SYSTEMKOMPONENTEN
P1 POS-Leser / E-Commerce
P2 Passinstance Core API
P3 Passinstance database-Datenbank & Journal
SCHRITT 1 ANFRAGE / AKTION POST/api/v1/reader/redeem
SCHRITT 2 ANFRAGE / AKTION Konto abrufen
›
(Aktueller Saldo)
SCHRITT 3 ANFRAGE / AKTION Invarianten prüfen:
›
Status === ACTIVE
›
Saldo >= Abbuchung
SCHRITT 4 ANFRAGE / AKTION Atomare Transaktion
›
prepaid account updaten
›
LedgerEntry anfügen
SCHRITT 5 ANTWORT 200 OK (resultingValue)
SCHRITT 6 ANFRAGE / AKTION Stiller APNs-Push
›
(Apple-Sperrbildschirm:
›
& Google REST PATCH
›
"12,50 € bezahlt.
›
Neuer Saldo: 37,50 €")

Regeln der Mechanik-Engine & Buchhaltungs-Schutzmechanismen

Der Pass Mechanics Engine setzt strenge finanzielle Invarianten bei Stored-Value-Operationen durch:

  1. 1
    Darstellung in kleinsten Währungseinheiten: Guthaben werden als Ganzzahlen in der kleinsten Währungseinheit berechnet (z. B. steht 2500 für 25,00 USD und 1550 für 15,50 EUR). Dadurch werden Gleitkomma-Rundungsfehler auch bei hochfrequenten Einzelhandelstransaktionen vollständig ausgeschlossen.
  2. 2
    Schutz vor negativem Saldo (disallowNegativeBalance: true): Der Server lehnt jede Abbuchungsanfrage ab, bei der currentBalanceMinor - debitAmountMinor < 0 gilt, und antwortet mit HTTP 400 sowie dem Fehlercode INSUFFICIENT_FUNDS.
  3. 3
    Auflade-Schutz (disableAutoRecharge: true): Verhindert automatische Aufladungen, sofern diese nicht ausdrücklich durch gespeicherte Zahlungsmethoden der Kundschaft autorisiert sind.
  4. 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

POST /api/v1/reader/redeem
Header
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"
}

HTTP-Antwort (200 OK)

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

Hinweis: Kassenpersonal kann Guthaben alternativ über POST /api/v1/scans (mit x-scanner-key) oder POST /api/v1/passes/:id/use / POST /api/v1/passes/:id/adjust-value (mit Bearer/API-Key-Auth) belasten oder aufladen und Buchungen über GET /api/v1/balance-changes?passId=<passId> prüfen. Stored-Value-Regeln unterstützen StoredValueOperation (NONE, ADD, SUBTRACT, SET) und StoredValueAmountSource (FIXED, OPERATOR, MECHANIC). Nutzen Sie externalId bei 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/:token bereitstellen und den Zahlungsstatus über GET /api/v1/public/reload-sessions/:sessionId/status abfragen.
  • Die Reload-Sitzung integriert sich mit Stripe, PayPal, Paystack oder Mobile Money (MTN MoMo, Orange Money), um Zahlungen abzuwickeln, das prepaid account sofort 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.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.