Panoramica
Gift card, buoni spesa negozio e wallet prepagati a circuito chiuso in Passinstance sono supportati da un mastro contabile immutabile in partita doppia (modelli prepaid account e prepaid ledger entry) anziché da un campo testuale privo di controlli. Tutti gli importi monetari sono archiviati e calcolati in unità valutarie minime intere (balanceMinor, ad esempio centesimi) con blocco rigoroso a livello di riga e invarianti di saldo non negativo (disallowNegativeBalance: true).
Importante: Le detrazioni sul valore memorizzato falliscono in modalità fail-closed con
decision: "FAILED"ereasonCode: "OUT_OF_BALANCE"ogni volta che l'addebito richiesto superabalanceMinorsu un account configurato condisallowNegativeBalance: true. Non esegua mai calcoli del saldo lato client; invii sempre il delta di transazione e lasci che il mastro backend effettui il commit del nuovo saldo.
Architettura del mastro a valore memorizzato
Interfacce per riscatto e rettifica del valore memorizzato
In base alla configurazione fisica di cassa o al flusso della console di supporto, è possibile scalare o ricaricare saldi prepagati tramite quattro endpoint dedicati:
| Interfaccia | Endpoint | Autenticazione | Caso d'uso principale | |||||
|---|---|---|---|---|---|---|---|---|
| Scanner mobile / web | POST /api/v1/scans | x-scanner-key | App scanner dello staff configurata con StoredValueOperation (`NONE | ADD | SUBTRACT | SET) e StoredValueAmountSource (FIXED | OPERATOR | MECHANIC`). |
| Lettore NFC hardware | POST /api/v1/reader/redeem | X-Reader-Secret | Orchestrazione server-to-reader che invia request payload (customerId, passId, amount, idempotencyKey). (Utilizzi POST /api/v1/reader/validate per la verifica di ingresso tramite codice a barre.) | |||||
| Terminale POS retail | POST /v1/pos/redeem | Terminale POS / Token Bearer | Casse integrate che eseguono PosOperation.DEDUCT_VALUE con passRef (serialNumber, codice a barre o externalId) e clientTxRef. | |||||
| Dashboard / Ricarica Admin | POST /api/v1/passes/:id/adjust-value | JWT Workspace / Chiave API (pass:manage) | Ricariche manuali gift card (action: "CREDIT"), rimborsi o rettifiche amministrative (action: "DEBIT"). |
1. Addebito tramite scanner da banco (POST /api/v1/scans)
Quando una ScannerConfiguration utilizza StoredValueOperation.SUBTRACT e StoredValueAmountSource.OPERATOR, il cassiere inserisce il totale dell'acquisto e invia:
/api/v1/scans
{
"scannedBarcodeValue": "PI-GFT-901244",
"scannerConfigurationId": "scfg_giftcard_debit",
"validationData": {
"amount": 24.50,
"currency": "EUR"
},
"operatorId": "emp_cashier_04"
}
Risposta (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. Orchestrazione lettori hardware (POST /api/v1/reader/redeem)
I gateway lato server per lettori contactless e ottici si autenticano tramite l'header X-Reader-Secret (reader integration secret) e inviano request payload direttamente a /api/v1/reader/redeem (quando amount viene omesso, il motore esegue VALIDATE; quando è presente, esegue 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"
}
Risposta (200 OK):
{
"success": true,
"resultingValue": "60.50"
}
3. Integrazione POS retail (POST /v1/pos/redeem)
I sistemi point-of-sale eseguono addebiti atomici con POST /v1/pos/redeem (esposto sotto /v1/pos, al di fuori di /api/v1). passRef corrisponde a qualsiasi token di pass, codice a barre, serialNumber oppure externalId upstream:
{
"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"
}
I valori PosOperation supportati sono DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID e CUSTOM. La risposta restituisce walletPropagation (PosWalletPropagationStatus: QUEUED o SKIPPED) quando vengono accodati aggiornamenti push live verso APNs/Google Wallet.
4. Ricariche manuali e rettifiche (POST /api/v1/passes/:id/adjust-value)
Per rimborsi, accrediti dell'assistenza clienti o ricariche di gift card dalla Dashboard o da un'integrazione ERP, richiami POST /api/v1/passes/:id/adjust-value con Idempotency-Key:
{
"action": "CREDIT",
"amount": "25.00",
"reason": "Customer return store credit",
"operatorId": "support_lead_02",
"idempotencyKey": "adj-20261116-0041"
}
Le azioni di rettifica supportate sono CREDIT (aggiunge saldo) e DEBIT (scala saldo).
Modello di mastro in partita doppia (prepaid account e prepaid ledger entry)
Ogni pass a valore memorizzato mantiene un record prepaid account associato a righe append-only prepaid ledger entry:
| Campo | Modello | Tipo | Descrizione |
|---|---|---|---|
balanceMinor | prepaid account | Int | Saldo attuale in unità valutarie minime (es. 7550 = €75.50). |
currency | prepaid account | String | Codice valuta ISO 4217 a 3 lettere (EUR, USD, GBP, CHF). |
disallowNegativeBalance | prepaid account | Boolean | Predefinito su true; impone balanceMinor >= 0 a livello di transazione del database. |
deltaMinor | prepaid ledger entry | Int | Variazione intera con segno (-2450 per addebito, +5000 per ricarica). |
balanceAfterMinor | prepaid ledger entry | Int | Snapshot di balanceMinor subito dopo l'inserimento della voce. |
idempotencyKey | prepaid ledger entry | String | Chiave di transazione univoca che impedisce doppi addebiti in caso di nuovi tentativi di rete. |
Per verificare tutti gli addebiti storici, le ricariche e i riferimenti operatore, interroghi GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger oppure GET /api/v1/balance-changes. Approfondisca in Gift card e carte prepagate e Lettori NFC compatibili.
