Ü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"sowiereasonCode: "OUT_OF_BALANCE", sobald der angeforderte AbzugbalanceMinorauf einem Konto mitdisallowNegativeBalance: 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
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äche | Endpunkt | Authentifizierung | Primärer Anwendungsfall | |||||
|---|---|---|---|---|---|---|---|---|
| Mobiler / Web-Scanner | POST /api/v1/scans | x-scanner-key | Mitarbeiter-Scanner-App mit StoredValueOperation (`NONE | ADD | SUBTRACT | SET) und StoredValueAmountSource (FIXED | OPERATOR | MECHANIC`). |
| Hardware-NFC-Lesegerät | POST /api/v1/reader/redeem | X-Reader-Secret | Server-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-Terminal | POST /v1/pos/redeem | POS-Terminal / Bearer-Token | Integrierte Kassensysteme, die PosOperation.DEDUCT_VALUE mit passRef (serialNumber, Barcode oder externalId) und clientTxRef ausführen. | |||||
| Dashboard / Admin-Aufladung | POST /api/v1/passes/:id/adjust-value | Arbeitsbereich-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:
/api/v1/scans
{
"scannedBarcodeValue": "PI-GFT-901244",
"scannerConfigurationId": "scfg_giftcard_debit",
"validationData": {
"amount": 24.50,
"currency": "EUR"
},
"operatorId": "emp_cashier_04"
}
Antwort (200 OK):
{
"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):
/api/v1/reader/redeem
{
"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):
{
"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:
{
"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:
{
"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:
| Feld | Modell | Typ | Beschreibung |
|---|---|---|---|
balanceMinor | prepaid account | Int | Aktueller Kontostand in kleinsten Währungseinheiten (z. B. 7550 = 75,50 EUR). |
currency | prepaid account | String | Dreistelliger ISO-4217-Währungscode (EUR, USD, GBP, CHF). |
disallowNegativeBalance | prepaid account | Boolean | Standardmäßig true; erzwingt balanceMinor >= 0 direkt auf Ebene der Datenbanktransaktion. |
deltaMinor | prepaid ledger entry | Int | Vorzeichenbehaftete Ganzzahl-Änderung (-2450 für Abbuchung, +5000 für Aufladung). |
balanceAfterMinor | prepaid ledger entry | Int | Momentaufnahme von balanceMinor unmittelbar nach der Buchung. |
idempotencyKey | prepaid ledger entry | String | Eindeutiger 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.
