Skip to content
Guida del Centro assistenzaFase di onboarding 2
3 min di letturaVerificato 2026-11-16

Gift card e carte prepagate

Configura la meccanica Valore memorizzato per carte prepagate ricaricabili con registro contabile verificabile.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito
Elementi chiave dell'interfaccia

Selettore «Aggiungi una meccanica pass» (Zoom)

Scegli tra 6 meccaniche integrate: Raccolta bollini, Riscatto bollini, Valore prepagato, Punti e livelli, Convalida giornaliera o Estensione scadenza.

Panoramica

Le gift card digitali e le carte prepagate a valore memorizzato permettono a negozi, caffetterie, gruppi alberghieri e retailer di emettere credito d'acquisto con il proprio brand direttamente in Apple Wallet e Google Wallet. I clienti portano sempre con sé il saldo disponibile sullo smartphone, mentre i team finance dispongono di un registro di audit immutabile a partita doppia per la riconciliazione contabile.

Architettura backend ed entità a valore memorizzato

La funzionalità di valore memorizzato in Passinstance si basa su modelli finanziari dedicati nello schema Passinstance database:

  • Tipo di pass (pass type): storeCard (mostra i saldi monetari in tempo reale nelle aree principali della tessera).
  • Modello demo a catalogo: gift-card.
  • Tipo di meccanica (mechanic type): PREPAID_CARD.
  • Modelli finanziari principali:

- prepaid account: Traccia il saldo monetario attivo utilizzando aritmetica intera in unità monetarie minime (balanceMinor) e codici valuta (currency: "EUR" | "USD"). - prepaid ledger entry: Registro contabile di audit immutabile che documenta ogni accredito, addebito, ricarica e rettifica con timestamp, ID operatore, riferimenti del terminale POS e chiavi di idempotenza.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
TRANSAZIONE LEDGER VALORE MEMORIZZATO
ATTORI DI SISTEMA COINVOLTI
P1 Lettore POS / E-Commerce
P2 Passinstance Core API
P3 Database Passinstance database e Ledger
FASE 1 RICHIESTA / AZIONE POST/api/v1/reader/redeem
FASE 2 RICHIESTA / AZIONE Recupera conto
›
(Saldo corrente)
FASE 3 RICHIESTA / AZIONE Verifiche invarianti:
›
Status === ACTIVE
›
Saldo >= Addebito
FASE 4 RICHIESTA / AZIONE Transazione atomica
›
Aggiorna prepaid account
›
Inserisce LedgerEntry
FASE 5 RISPOSTA 200 OK (resultingValue)
FASE 6 RICHIESTA / AZIONE Push APNs silenziosa
›
(Lock-screen Apple:
›
& PATCH REST Google
›
"Paid €12.50. New
›
balance: €37.50")

Regole del motore meccaniche e protezioni contabili

Pass Mechanics Engine applica rigorose invarianti finanziarie sulle operazioni a valore memorizzato:

  1. 1
    Rappresentazione in unità monetarie minime: I saldi vengono calcolati in unità minime intere (ad esempio 2500 rappresenta $25.00 USD e 1550 rappresenta €15.50 EUR). Ciò elimina errori di arrotondamento in virgola mobile nelle transazioni retail ad alta frequenza.
  2. 2
    Prevenzione saldi negativi (disallowNegativeBalance: true): Il server rifiuta rigorosamente qualsiasi richiesta di addebito in cui currentBalanceMinor - debitAmountMinor < 0, restituendo HTTP 400 con codice errore INSUFFICIENT_FUNDS.
  3. 3
    Protezioni sulle ricariche (disableAutoRecharge: true): Impedisce attivazioni di ricarica automatica se non esplicitamente autorizzate dai metodi di pagamento salvati dal cliente.
  4. 4
    Protezione con idempotenza: Ogni richiesta di addebito o ricarica accetta una idempotencyKey univoca. Eventuali richieste duplicate provenienti dal POS per retry di rete restituiscono in sicurezza la risposta positiva originaria senza doppio addebito.

Riscatto atomico al POS e ricarica del saldo

Operatori di cassa, hardware POS integrato e casse self-checkout comunicano con la Reader Orchestration API oppure con gli endpoint di scansione in cassa:

Richiesta HTTP

POST /api/v1/reader/redeem
Header
X-Reader-Secret <reader integration secret>
Content-Type application/json
JSON
{
  "customerId": "8f94d930-b302-4fc8-9f12-000000000001",
  "passId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
  "amount": "12.50",
  "idempotencyKey": "pos_tx_20261115_0091",
  "operatorId": "cashier_alex"
}

Risposta HTTP (200 OK)

JSON
{
  "success": true,
  "resultingValue": "37.50"
}

Nota: Il personale di cassa può anche addebitare o accreditare saldi utilizzando POST /api/v1/scans (con x-scanner-key) oppure POST /api/v1/passes/:id/use / POST /api/v1/passes/:id/adjust-value (con autenticazione Bearer/Chiave API), oltre a verificare le transazioni tramite GET /api/v1/balance-changes?passId=<passId>. Le regole a valore memorizzato supportano StoredValueOperation (NONE, ADD, SUBTRACT, SET) e StoredValueAmountSource (FIXED, OPERATOR, MECHANIC). Utilizzi externalId alla creazione per correlare le carte Wallet ai numeri gift card di un POS esterno.

Sessioni pubbliche di ricarica per i clienti

I titolari delle carte possono controllare il saldo e aggiungere credito d'acquisto online:

  • I merchant possono generare link di auto-ricarica supportati da GET /api/v1/public/reload-sessions/:token e interrogare lo stato del pagamento su GET /api/v1/public/reload-sessions/:sessionId/status.
  • La sessione di ricarica si integra con Stripe, PayPal, Paystack o Mobile Money (MTN MoMo, Orange Money) per elaborare il pagamento, accreditare istantaneamente prepaid account e inviare il saldo aggiornato ad Apple Wallet e Google Wallet.

Importante: Configuri sempre changeMessage: "New balance: %@" sul campo del saldo nell'editor visuale del modello. Quando avviene un addebito o una ricarica, lo smartphone del cliente si risveglia immediatamente con una notifica nativa sulla schermata di blocco che mostra il nuovo credito disponibile.

Scopra di più sul nostro Caso d'uso Gift card.

Documentazione prodotto e API correlata

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.