Overview
Digital gift cards and prepaid stored-value cards allow merchants, cafes, hospitality brands, and retailers to issue branded purchasing credit directly to Apple Wallet and Google Wallet. Customers always carry their available balance on their smartphones, while finance teams maintain an immutable, double-entry audit ledger for financial reconciliation.
Backend Architecture & Stored Value Entities
Stored value functionality in Passinstance is driven by dedicated financial balance models in the Passinstance data model:
-
Pass Type (pass type):
storeCard(displays live monetary balances prominently in primary card zones). -
Catalog Demo Blueprint:
gift-card. -
Mechanic Type (mechanic type):
PREPAID_CARD. -
Primary Financial Models:
- prepaid account: Tracks the active monetary balance using integer arithmetic in minor currency units (balanceMinor) and currency codes (currency: "EUR" | "USD"). - prepaid ledger entry: Immutable audit ledger recording every credit, debit, reload, and adjustment with timestamps, operator IDs, POS terminal references, and idempotency keys.
Mechanic Engine Rules & Accounting Guardrails
The Pass Mechanics Engine enforces strict financial invariants on stored value operations:
-
1
Minor Currency Unit Representation: Balances are calculated in integer minor units (e.g.
2500represents $25.00 USD, and1550represents €15.50 EUR). This eliminates floating-point rounding errors across high-frequency retail transactions. -
2
Negative Balance Prevention (
disallowNegativeBalance: true): The server strictly rejects any debit request wherecurrentBalanceMinor - debitAmountMinor < 0, returning HTTP 400 with error codeINSUFFICIENT_FUNDS. -
3
Recharge Guardrails (
disableAutoRecharge: true): Prevents automated reload triggers unless explicitly authorized by customer saved payment methods. -
4
Idempotency Protection: Every debit or reload request accepts a unique
idempotencyKey. Duplicate POS requests caused by network retries safely return the original successful response without double-charging the customer.
Atomic POS Redemption & Balance Top-Up
Cash register operators, integrated POS hardware, and automated self-checkout terminals communicate with the Reader Orchestration API or counter scan endpoints:
HTTP Request
/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"
}
HTTP Response (200 OK)
{
"success": true,
"resultingValue": "37.50"
}
Note: Counter staff can also debit or credit balances using
POST /api/v1/scans(withx-scanner-key) orPOST /api/v1/passes/:id/use/POST /api/v1/passes/:id/adjust-value(with Bearer/API Key auth), and audit transactions viaGET /api/v1/balance-changes?passId=<passId>. Stored value rules supportStoredValueOperation(NONE,ADD,SUBTRACT,SET) andStoredValueAmountSource(FIXED,OPERATOR,MECHANIC). UseexternalIdon creation to correlate wallet cards with external POS gift card numbers.
Public Customer Reload Sessions
Cardholders can check balances and add purchasing credit online:
-
Merchants can issue self-reload links backed by
GET /api/v1/public/reload-sessions/:tokenand poll payment status onGET /api/v1/public/reload-sessions/:sessionId/status. -
The reload session integrates with Stripe, PayPal, Paystack, or Mobile Money (MTN MoMo, Orange Money) to process payment, instantly credit the
prepaid account, and push the updated balance to Apple Wallet and Google Wallet.
Important: Always configure
changeMessage: "New balance: %@"on the balance field in the visual template editor. When a debit or reload occurs, the customer's phone immediately wakes with a native lock-screen notification showing the new available balance.
Discover more on our Gift Cards Use Case.
