Skip to content
Hilfecenter-Anleitung · Einlösung & Transaktionen
3 Min. LesezeitGeprüft 2026-11-16

Geschenkkarten- & Guthabeneinlösung

Buchen Sie Einkäufe ab, verarbeiten Sie Aufladungen, verhindern Sie Negativsalden und prüfen Sie Transaktionsjournale.

In dieser Anleitung

Überblick

Geschenkkarten, Filialguthaben-Pässe und geschlossene Prepaid-Wallets werden in Passinstance durch ein unveränderliches Ledger nach dem Prinzip der doppelten Buchführung gestützt (prepaid account- und prepaid ledger entry-Modelle) statt über ungeschützte Textfelder. Sämtliche Geldbeträge werden in ganzzahligen kleinsten Währungseinheiten (balanceMinor, etwa Cent) mit strikter Zeilen-Sperrung (Row-Level Locking) und Invarianten gegen negative Salden (disallowNegativeBalance: true) gespeichert und berechnet.

Wichtig: Wertguthaben-Abbuchungen schlagen fehl und schließen sicher mit decision: "FAILED" sowie reasonCode: "OUT_OF_BALANCE", sobald der angeforderte Abzug balanceMinor auf einem Konto mit disallowNegativeBalance: true überschreitet. Berechnen Sie Salden niemals clientseitig; übermitteln Sie stets nur das Transaktionsdelta und überlassen Sie dem Backend-Ledger die Buchung des neuen Guthabens.

Architektur des Wertguthaben-Ledgers

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
PREPAID-LEDGER-ABBUCHUNG & HARDWARE-LESER-EINLÖSUNG
BETEILIGTE SYSTEMKOMPONENTEN
P1 Scanner / Hardware-Leser
P2 Scan / Reader / POS Controller
P3 prepaid account & Ledger DB
SCHRITT 1a ANFRAGE / AKTION POST/api/v1/scans
›
(StoredValueOp.SUBTRACT)
SCHRITT 1b ANFRAGE / AKTION POST/api/v1/reader/redeem
SCHRITT 2 ANFRAGE / AKTION SELECT ... FOR UPDATE
SCHRITT 1c ANFRAGE / AKTION POST/v1/pos/redeem
›
(prepaid account-Zeile sperren)
›
(operation: DEDUCT_VALUE)
SCHRITT 3 ANFRAGE / AKTION disallowNegativeBalance prüfen:
›
balanceMinor >= amountMinor
SCHRITT 4 ANFRAGE / AKTION prepaid ledger entry einfügen
›
& balanceMinor aktualisieren
SCHRITT 5 ANTWORT 200 OK (remainingBalance)
SCHRITT 6 ANFRAGE / AKTION APNs / Google Push auslösen

Oberflächen für Wertguthaben-Einlösung & -Anpassung

Je nach Kassenaufbau vor Ort oder Support-Konsolen-Ablauf können Sie Prepaid-Guthaben über vier dedizierte Endpunkte abbuchen oder aufladen:

OberflächeEndpunktAuthentifizierungPrimärer Anwendungsfall
Mobiler / Web-ScannerPOST /api/v1/scansx-scanner-keyMitarbeiter-Scanner-App mit StoredValueOperation (`NONEADDSUBTRACTSET) und StoredValueAmountSource (FIXEDOPERATORMECHANIC`).
Hardware-NFC-LesegerätPOST /api/v1/reader/redeemX-Reader-SecretServer-to-Reader-Orchestrierung mit request payload (customerId, passId, amount, idempotencyKey). (Verwenden Sie POST /api/v1/reader/validate für die Prüfung optischer Barcode-Eingaben.)
Einzelhandels-POS-TerminalPOST /v1/pos/redeemPOS-Terminal / Bearer-TokenIntegrierte Kassensysteme, die PosOperation.DEDUCT_VALUE mit passRef (serialNumber, Barcode oder externalId) und clientTxRef ausführen.
Dashboard / Admin-AufladungPOST /api/v1/passes/:id/adjust-valueArbeitsbereich-JWT / API-Schlüssel (pass:manage)Manuelle Geschenkkarten-Aufladungen (action: "CREDIT"), Erstattungen oder administrative Korrekturen (action: "DEBIT").

1. Abbuchung über Kassen-Scanner (POST /api/v1/scans)

Verwendet eine ScannerConfiguration die Optionen StoredValueOperation.SUBTRACT und StoredValueAmountSource.OPERATOR, gibt das Kassenpersonal den Kaufbetrag ein und übermittelt:

POST /api/v1/scans
Headers
x-scanner-key sk_live_gift_register_02
x-idempotency-key scan-debit-20261116-4401
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "PI-GFT-901244",
  "scannerConfigurationId": "scfg_giftcard_debit",
  "validationData": {
    "amount": 24.50,
    "currency": "EUR"
  },
  "operatorId": "emp_cashier_04"
}

Antwort (200 OK):

JSON
{
  "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. Hardware-Reader-Orchestrierung (POST /api/v1/reader/redeem)

Serverseitige Gateways für kontaktlose und optische Lesegeräte authentifizieren sich mit dem Header X-Reader-Secret (reader integration secret) und übermitteln request payload direkt an /api/v1/reader/redeem (fehlt amount, führt die Engine VALIDATE aus; ist ein Betrag angegeben, bucht sie mit DEBIT ab):

POST /api/v1/reader/redeem
Headers
X-Reader-Secret rsec_live_reader_terminal_09a8f1
Content-Type application/json
JSON
{
  "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"
}

Antwort (200 OK):

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

3. Einzelhandels-POS-Integration (POST /v1/pos/redeem)

Kassensysteme führen atomare Abbuchungen mit POST /v1/pos/redeem aus (eingebunden unter /v1/pos, außerhalb von /api/v1). passRef findet Pässe über Token, Barcode, serialNumber oder Ihre vorgelagerte externalId:

JSON
{
  "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"
}

Unterstützte PosOperation-Werte sind DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID und CUSTOM. Die Antwort liefert walletPropagation (PosWalletPropagationStatus: QUEUED oder SKIPPED), sobald Live-Push-Updates an APNs bzw. Google Wallet in die Warteschlange gestellt werden.

4. Manuelle Aufladungen & Korrekturen (POST /api/v1/passes/:id/adjust-value)

Für Rückerstattungen, Kulanzgutschriften im Kundenservice oder Geschenkkarten-Aufladungen über das Dashboard bzw. eine ERP-Integration rufen Sie POST /api/v1/passes/:id/adjust-value mit Idempotency-Key auf:

JSON
{
  "action": "CREDIT",
  "amount": "25.00",
  "reason": "Customer return store credit",
  "operatorId": "support_lead_02",
  "idempotencyKey": "adj-20261116-0041"
}

Unterstützte Anpassungsaktionen sind CREDIT (Guthaben hinzufügen) und DEBIT (Guthaben abziehen).

Doppeltes-Buchführungs-Ledger-Modell (prepaid account & prepaid ledger entry)

Jeder Wertguthaben-Pass verwaltet einen prepaid account-Datensatz in Verbindung mit unveränderlichen, nur anhängenden (append-only) prepaid ledger entry-Zeilen:

FeldModellTypBeschreibung
balanceMinorprepaid accountIntAktueller Kontostand in kleinsten Währungseinheiten (z. B. 7550 = 75,50 EUR).
currencyprepaid accountStringDreistelliger ISO-4217-Währungscode (EUR, USD, GBP, CHF).
disallowNegativeBalanceprepaid accountBooleanStandardmäßig true; erzwingt balanceMinor >= 0 direkt auf Ebene der Datenbanktransaktion.
deltaMinorprepaid ledger entryIntVorzeichenbehaftete Ganzzahl-Änderung (-2450 für Abbuchung, +5000 für Aufladung).
balanceAfterMinorprepaid ledger entryIntMomentaufnahme von balanceMinor unmittelbar nach der Buchung.
idempotencyKeyprepaid ledger entryStringEindeutiger Transaktionsschlüssel zur Vermeidung doppelter Abbuchungen bei Netzwerk-Wiederholungen.

Um alle historischen Abbuchungen, Aufladungen und Bedienerreferenzen zu prüfen, fragen Sie GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger oder GET /api/v1/balance-changes ab. Weitere Details finden Sie unter Geschenkkarten & Prepaid-Karten und Kompatible NFC-Lesegeräte.

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.