Overzicht
Cadeaubonnen, winkeltegoedpassen en closed-loop prepaid-wallets in Passinstance worden ondersteund door een onveranderlijk dubbel boekhoudgrootboek (de modellen prepaid account en prepaid ledger entry) in plaats van een onbeveiligd tekstveld. Alle geldbedragen worden opgeslagen en berekend in gehele kleinere valutaeenheden (balanceMinor, zoals eurocenten) met strikte vergrendeling op rijniveau en niet-negatieve saldo-invarianten (disallowNegativeBalance: true).
Belangrijk: Afschrijvingen van tegoeden weigeren standaard (fail-closed) met
decision: "FAILED"enreasonCode: "OUT_OF_BALANCE"zodra de gevraagde afschrijving hoger is danbalanceMinorop een account dat is geconfigureerd metdisallowNegativeBalance: true. Bereken saldowerkingen nooit op de client; dien altijd het transactieverschil in en laat het backend-grootboek het nieuwe saldo vastleggen.
Architectuur van het tegoedgrootboek
Oppervlakken voor tegoedverzilvering en -aanpassing
Afhankelijk van uw fysieke kassa-opstelling of de workflow in uw ondersteuningsconsole kunt u prepaid-saldi afschrijven of opwaarderen via vier speciale eindpunten:
| Oppervlak | Eindpunt | Authenticatie | Primair gebruiksscenario | |||||
|---|---|---|---|---|---|---|---|---|
| Mobiele / Webscanner | POST /api/v1/scans | x-scanner-key | Scanner-app voor personeel geconfigureerd met StoredValueOperation (`NONE | ADD | SUBTRACT | SET) en StoredValueAmountSource (FIXED | OPERATOR | MECHANIC`). |
| Hardwarematige NFC-lezer | POST /api/v1/reader/redeem | X-Reader-Secret | Server-naar-lezer orkestratie die request payload (customerId, passId, amount, idempotencyKey) indient. (Gebruik POST /api/v1/reader/validate voor toegangsverificatie via barcodes.) | |||||
| Retail POS-terminal | POST /v1/pos/redeem | POS-terminal / Bearer-token | Geïntegreerde kassasystemen die PosOperation.DEDUCT_VALUE uitvoeren met passRef (serialNumber, barcode of externalId) en clientTxRef. | |||||
| Dashboard / Admin-opwaardering | POST /api/v1/passes/:id/adjust-value | Werkruimte-JWT / API-sleutel (pass:manage) | Handmatige opwaarderingen van cadeaubonnen (action: "CREDIT"), terugbetalingen of administratieve correcties (action: "DEBIT"). |
1. Afschrijving via baliescanner (POST /api/v1/scans)
Wanneer een ScannerConfiguration gebruikmaakt van StoredValueOperation.SUBTRACT en StoredValueAmountSource.OPERATOR, voert de kassamedewerker het aankoopbedrag in en verstuurt:
/api/v1/scans
{
"scannedBarcodeValue": "PI-GFT-901244",
"scannerConfigurationId": "scfg_giftcard_debit",
"validationData": {
"amount": 24.50,
"currency": "EUR"
},
"operatorId": "emp_cashier_04"
}
Antwoord (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. Orkestratie van hardwarelezers (POST /api/v1/reader/redeem)
Server-side contactloze en optische lezergateways authenticeren met behulp van de X-Reader-Secret-header (reader integration secret) en dienen request payload rechtstreeks in bij /api/v1/reader/redeem (wanneer amount wordt weggelaten, voert de engine VALIDATE uit; wanneer het wordt meegegeven, voert deze DEBIT uit):
/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"
}
Antwoord (200 OK):
{
"success": true,
"resultingValue": "60.50"
}
3. Retail POS-integratie (POST /v1/pos/redeem)
Point-of-sale-systemen voeren atomaire afschrijvingen uit met POST /v1/pos/redeem (gekoppeld onder /v1/pos, buiten /api/v1). passRef komt overeen met elk pastoken, elke barcode, serialNumber of uw eigen 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"
}
Ondersteunde PosOperation-waarden zijn DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID en CUSTOM. Het antwoord retourneert walletPropagation (PosWalletPropagationStatus: QUEUED of SKIPPED) wanneer live push-updates in de wachtrij worden geplaatst voor APNs/Google Wallet.
4. Handmatige opwaarderingen en correcties (POST /api/v1/passes/:id/adjust-value)
Voor terugbetalingen, tegoeden vanuit de klantenservice of opwaarderingen van cadeaubonnen vanuit het Dashboard of een ERP-integratie, roept u POST /api/v1/passes/:id/adjust-value aan met Idempotency-Key:
{
"action": "CREDIT",
"amount": "25.00",
"reason": "Customer return store credit",
"operatorId": "support_lead_02",
"idempotencyKey": "adj-20261116-0041"
}
Ondersteunde aanpassingsacties zijn CREDIT (saldo bijschrijven) en DEBIT (saldo afschrijven).
Dubbel boekhoudgrootboekmodel (prepaid account & prepaid ledger entry)
Elke tegoedpas onderhoudt een prepaid account-record gekoppeld aan alleen-toevoegbare (append-only) prepaid ledger entry-rijen:
| Veld | Model | Type | Beschrijving |
|---|---|---|---|
balanceMinor | prepaid account | Int | Huidig saldo in kleinere valutaeenheden (bijv. 7550 = €75,50). |
currency | prepaid account | String | ISO 4217 3-letterige valutacode (EUR, USD, GBP, CHF). |
disallowNegativeBalance | prepaid account | Boolean | Standaard ingesteld op true; dwingt balanceMinor >= 0 af op het niveau van de databasetransactie. |
deltaMinor | prepaid ledger entry | Int | Gehele wijziging met teken (-2450 voor afschrijving, +5000 voor opwaardering). |
balanceAfterMinor | prepaid ledger entry | Int | Momentopname van balanceMinor onmiddellijk na de boeking. |
idempotencyKey | prepaid ledger entry | String | Unieke transactiesleutel die dubbele afschrijvingen voorkomt bij nieuwe netwerkpogingen. |
Om alle historische afschrijvingen, opwaarderingen en operatorreferenties te controleren, bevraagt u GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger of GET /api/v1/balance-changes. Lees meer in Cadeaubonnen en prepaidkaarten en Compatibele NFC-lezers.
