Skip to content
Helpcentrum-gids · Inwisseling & transacties
3 min leestijdGecontroleerd 2026-11-16

Cadeaukaart- & saldotransacties

Schrijf aankopen af, waardeer prepaidkaarten op, voorkom negatieve saldi en bekijk het mutatieoverzicht.

In deze gids

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" en reasonCode: "OUT_OF_BALANCE" zodra de gevraagde afschrijving hoger is dan balanceMinor op een account dat is geconfigureerd met disallowNegativeBalance: 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

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SYSTEEMARCHITECTUURSTROOM: PREPAID-GROOTBOEKAFSCHRIJVING & VERZILVERING VIA HARDWARELEZER
DEELNEMENDE SYSTEEMACTOREN
P1 Scanner / Hardwarelezer
P2 Scan- / Reader- / POS-controller
P3 prepaid account & Grootboek-DB
STAP 1a VERZOEK / ACTIE POST/api/v1/scans
›
(StoredValueOp.SUBTRACT)
STAP 1b VERZOEK / ACTIE POST/api/v1/reader/redeem
STAP 2 VERZOEK / ACTIE SELECT ... FOR UPDATE
STAP 1c VERZOEK / ACTIE POST/v1/pos/redeem
›
(Vergrendel prepaid account)
›
(operation: DEDUCT_VALUE)
STAP 3 VERZOEK / ACTIE Check disallowNegativeBalance:
›
balanceMinor >= amountMinor
STAP 4 VERZOEK / ACTIE Voeg prepaid ledger entry in
›
& werk balanceMinor bij
STAP 5 ANTWOORD 200 OK (remainingBalance)
STAP 6 VERZOEK / ACTIE Activeer APNs / Google Push

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:

OppervlakEindpuntAuthenticatiePrimair gebruiksscenario
Mobiele / WebscannerPOST /api/v1/scansx-scanner-keyScanner-app voor personeel geconfigureerd met StoredValueOperation (`NONEADDSUBTRACTSET) en StoredValueAmountSource (FIXEDOPERATORMECHANIC`).
Hardwarematige NFC-lezerPOST /api/v1/reader/redeemX-Reader-SecretServer-naar-lezer orkestratie die request payload (customerId, passId, amount, idempotencyKey) indient. (Gebruik POST /api/v1/reader/validate voor toegangsverificatie via barcodes.)
Retail POS-terminalPOST /v1/pos/redeemPOS-terminal / Bearer-tokenGeïntegreerde kassasystemen die PosOperation.DEDUCT_VALUE uitvoeren met passRef (serialNumber, barcode of externalId) en clientTxRef.
Dashboard / Admin-opwaarderingPOST /api/v1/passes/:id/adjust-valueWerkruimte-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:

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

Antwoord (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. 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):

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

Antwoord (200 OK):

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

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

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:

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

VeldModelTypeBeschrijving
balanceMinorprepaid accountIntHuidig saldo in kleinere valutaeenheden (bijv. 7550 = €75,50).
currencyprepaid accountStringISO 4217 3-letterige valutacode (EUR, USD, GBP, CHF).
disallowNegativeBalanceprepaid accountBooleanStandaard ingesteld op true; dwingt balanceMinor >= 0 af op het niveau van de databasetransactie.
deltaMinorprepaid ledger entryIntGehele wijziging met teken (-2450 voor afschrijving, +5000 voor opwaardering).
balanceAfterMinorprepaid ledger entryIntMomentopname van balanceMinor onmiddellijk na de boeking.
idempotencyKeyprepaid ledger entryStringUnieke 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.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.