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.
Regole del motore meccaniche e protezioni contabili
Pass Mechanics Engine applica rigorose invarianti finanziarie sulle operazioni a valore memorizzato:
-
1
Rappresentazione in unità monetarie minime: I saldi vengono calcolati in unità minime intere (ad esempio
2500rappresenta $25.00 USD e1550rappresenta €15.50 EUR). Ciò elimina errori di arrotondamento in virgola mobile nelle transazioni retail ad alta frequenza. -
2
Prevenzione saldi negativi (
disallowNegativeBalance: true): Il server rifiuta rigorosamente qualsiasi richiesta di addebito in cuicurrentBalanceMinor - debitAmountMinor < 0, restituendo HTTP 400 con codice erroreINSUFFICIENT_FUNDS. -
3
Protezioni sulle ricariche (
disableAutoRecharge: true): Impedisce attivazioni di ricarica automatica se non esplicitamente autorizzate dai metodi di pagamento salvati dal cliente. -
4
Protezione con idempotenza: Ogni richiesta di addebito o ricarica accetta una
idempotencyKeyunivoca. 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
/api/v1/reader/redeem
{
"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)
{
"success": true,
"resultingValue": "37.50"
}
Nota: Il personale di cassa può anche addebitare o accreditare saldi utilizzando
POST /api/v1/scans(conx-scanner-key) oppurePOST /api/v1/passes/:id/use/POST /api/v1/passes/:id/adjust-value(con autenticazione Bearer/Chiave API), oltre a verificare le transazioni tramiteGET /api/v1/balance-changes?passId=<passId>. Le regole a valore memorizzato supportanoStoredValueOperation(NONE,ADD,SUBTRACT,SET) eStoredValueAmountSource(FIXED,OPERATOR,MECHANIC). UtilizziexternalIdalla 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/:tokene interrogare lo stato del pagamento suGET /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 accounte 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.
