Overview
Gift cards, store credit passes, and closed-loop prepaid wallets in Passinstance are backed by an immutable double-entry ledger (prepaid account and prepaid ledger entry models) rather than an unguarded text field. All monetary amounts are stored and calculated in integer minor currency units (balanceMinor, such as cents) with strict row-level locking and non-negative balance invariants (disallowNegativeBalance: true).
Important: Stored-value deductions fail closed with
decision: "FAILED"andreasonCode: "OUT_OF_BALANCE"whenever the requested deduction exceedsbalanceMinoron an account configured withdisallowNegativeBalance: true. Never compute balance math on the client; always submit the transaction delta and let the backend ledger commit the new balance.
Stored-Value Ledger Architecture
Stored-Value Redemption & Adjustment Surfaces
Depending on your physical checkout setup or support console workflow, you can deduct or reload prepaid balances across four dedicated endpoints:
| Surface | Endpoint | Authentication | Primary Use Case | |||||
|---|---|---|---|---|---|---|---|---|
| Mobile / Web Scanner | POST /api/v1/scans | x-scanner-key | Staff scanner app configured with StoredValueOperation (`NONE | ADD | SUBTRACT | SET) and StoredValueAmountSource (FIXED | OPERATOR | MECHANIC`). |
| Hardware NFC Reader | POST /api/v1/reader/redeem | X-Reader-Secret | Server-to-reader orchestration submitting request payload (customerId, passId, amount, idempotencyKey). (Use POST /api/v1/reader/validate for barcode entry verification.) | |||||
| Retail POS Terminal | POST /v1/pos/redeem | POS Terminal / Bearer Token | Integrated cash registers executing PosOperation.DEDUCT_VALUE with passRef (serialNumber, barcode, or externalId) and clientTxRef. | |||||
| Dashboard / Admin Reload | POST /api/v1/passes/:id/adjust-value | Workspace JWT / API Key (pass:manage) | Manual gift card top-ups (action: "CREDIT"), refunds, or administrative corrections (action: "DEBIT"). |
1. Counter Scanner Debit (POST /api/v1/scans)
When a ScannerConfiguration uses StoredValueOperation.SUBTRACT and StoredValueAmountSource.OPERATOR, the cashier enters the purchase total and submits:
/api/v1/scans
{
"scannedBarcodeValue": "PI-GFT-901244",
"scannerConfigurationId": "scfg_giftcard_debit",
"validationData": {
"amount": 24.50,
"currency": "EUR"
},
"operatorId": "emp_cashier_04"
}
Response (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 Orchestration (POST /api/v1/reader/redeem)
Server-side contactless and optical reader gateways authenticate using the X-Reader-Secret header (reader integration secret) and submit request payload directly to /api/v1/reader/redeem (when amount is omitted, the engine performs VALIDATE; when provided, it executes DEBIT):
/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"
}
Response (200 OK):
{
"success": true,
"resultingValue": "60.50"
}
3. Retail POS Integration (POST /v1/pos/redeem)
Point-of-sale systems execute atomic deductions with POST /v1/pos/redeem (mounted under /v1/pos, outside /api/v1). passRef matches any pass token, barcode, serialNumber, or your upstream 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"
}
Supported PosOperation values are DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, and CUSTOM. The response returns walletPropagation (PosWalletPropagationStatus: QUEUED or SKIPPED) when live push updates are queued to APNs/Google Wallet.
4. Manual Reloads & Corrections (POST /api/v1/passes/:id/adjust-value)
For refunds, customer service credits, or gift card reloads from the Dashboard or an ERP integration, call POST /api/v1/passes/:id/adjust-value with Idempotency-Key:
{
"action": "CREDIT",
"amount": "25.00",
"reason": "Customer return store credit",
"operatorId": "support_lead_02",
"idempotencyKey": "adj-20261116-0041"
}
Supported adjustment actions are CREDIT (add balance) and DEBIT (subtract balance).
Double-Entry Ledger Model (prepaid account & prepaid ledger entry)
Every stored-value pass maintains a prepaid account record paired with append-only prepaid ledger entry rows:
| Field | Model | Type | Description |
|---|---|---|---|
balanceMinor | prepaid account | Int | Current balance in minor currency units (e.g., 7550 = €75.50). |
currency | prepaid account | String | ISO 4217 3-letter currency code (EUR, USD, GBP, CHF). |
disallowNegativeBalance | prepaid account | Boolean | Defaults to true; enforces balanceMinor >= 0 at the database transaction layer. |
deltaMinor | prepaid ledger entry | Int | Signed integer change (-2450 for debit, +5000 for reload). |
balanceAfterMinor | prepaid ledger entry | Int | Snapshot of balanceMinor immediately following the entry. |
idempotencyKey | prepaid ledger entry | String | Unique transaction key preventing duplicate debits on network retry. |
To audit all historical debits, top-ups, and operator references, query GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger or GET /api/v1/balance-changes. Learn more in Gift Cards & Prepaid Cards and Compatible NFC Readers.
