Skip to content
Guida del Centro assistenza · Riscatti e transazioni
4 min di letturaVerificato 2026-11-16

Gestione saldo Gift Card e prepagate

Scala importi di acquisto, esegui ricariche, impedisci saldi negativi e consulta il registro movimenti.

In questa guida

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" e reasonCode: "OUT_OF_BALANCE" ogni volta che l'addebito richiesto supera balanceMinor su un account configurato con disallowNegativeBalance: 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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
ADDEBITO SU MASTRO PREPAGATO E RISCATTO DA LETTORE HARDWARE
ATTORI DI SISTEMA COINVOLTI
P1 Scanner / Lettore Hardware
P2 Controller Scan / Reader / POS
P3 DB prepaid account e Ledger
FASE 1a RICHIESTA / AZIONE POST/api/v1/scans
›
(StoredValueOp.SUBTRACT)
FASE 1b RICHIESTA / AZIONE POST/api/v1/reader/redeem
FASE 2 RICHIESTA / AZIONE SELECT ... FOR UPDATE
FASE 1c RICHIESTA / AZIONE POST/v1/pos/redeem
›
(Blocca riga prepaid account)
›
(operation: DEDUCT_VALUE)
FASE 3 RICHIESTA / AZIONE Verifica disallowNegativeBalance:
›
balanceMinor >= amountMinor
FASE 4 RICHIESTA / AZIONE Inserisce prepaid ledger entry
›
e aggiorna balanceMinor
FASE 5 RISPOSTA 200 OK (remainingBalance)
FASE 6 RICHIESTA / AZIONE Avvia push APNs / Google

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:

InterfacciaEndpointAutenticazioneCaso d'uso principale
Scanner mobile / webPOST /api/v1/scansx-scanner-keyApp scanner dello staff configurata con StoredValueOperation (`NONEADDSUBTRACTSET) e StoredValueAmountSource (FIXEDOPERATORMECHANIC`).
Lettore NFC hardwarePOST /api/v1/reader/redeemX-Reader-SecretOrchestrazione 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 retailPOST /v1/pos/redeemTerminale POS / Token BearerCasse integrate che eseguono PosOperation.DEDUCT_VALUE con passRef (serialNumber, codice a barre o externalId) e clientTxRef.
Dashboard / Ricarica AdminPOST /api/v1/passes/:id/adjust-valueJWT 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:

POST /api/v1/scans
Header
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"
}

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

POST /api/v1/reader/redeem
Header
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"
}

Risposta (200 OK):

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

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

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:

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

CampoModelloTipoDescrizione
balanceMinorprepaid accountIntSaldo attuale in unità valutarie minime (es. 7550 = €75.50).
currencyprepaid accountStringCodice valuta ISO 4217 a 3 lettere (EUR, USD, GBP, CHF).
disallowNegativeBalanceprepaid accountBooleanPredefinito su true; impone balanceMinor >= 0 a livello di transazione del database.
deltaMinorprepaid ledger entryIntVariazione intera con segno (-2450 per addebito, +5000 per ricarica).
balanceAfterMinorprepaid ledger entryIntSnapshot di balanceMinor subito dopo l'inserimento della voce.
idempotencyKeyprepaid ledger entryStringChiave 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.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.