Skip to content
Help Center GuideOnboarding Phase 2
3 min readVerified 2026-11-16

Gift Cards & Prepaid Cards

Configure Stored Value mechanics for purchasable or reloadable wallet gift cards with auditable ledger balances.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Add a Pass Mechanic selector (Zoomed)

Choose from 6 built-in mechanics: Stamp Pass, Stamp Redemption, Stored Value, Points & Tiers, Once-per-day validation, or Extend Expiry.

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.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
STORED VALUE LEDGER TRANSACTION
PARTICIPATING SYSTEM ACTORS
P1 POS Reader / E-Commerce
P2 Passinstance Core API
P3 Passinstance Database & Ledger
STEP 1 REQUEST / ACTION POST/api/v1/reader/redeem
STEP 2 REQUEST / ACTION Fetch Account
›
(Current Balance)
STEP 3 REQUEST / ACTION Invariant Checks:
›
Status === ACTIVE
›
Balance >= Debit
STEP 4 REQUEST / ACTION Atomic Transaction
›
Update prepaid account
›
Insert LedgerEntry
STEP 5 RESPONSE 200 OK (resultingValue)
STEP 6 REQUEST / ACTION Silent APNs Push
›
(Apple Lock-Screen
›
& Google REST PATCH
›
"Paid €12.50. New
›
balance: €37.50")

Mechanic Engine Rules & Accounting Guardrails

The Pass Mechanics Engine enforces strict financial invariants on stored value operations:

  1. 1
    Minor Currency Unit Representation: Balances are calculated in integer minor units (e.g. 2500 represents $25.00 USD, and 1550 represents €15.50 EUR). This eliminates floating-point rounding errors across high-frequency retail transactions.
  2. 2
    Negative Balance Prevention (disallowNegativeBalance: true): The server strictly rejects any debit request where currentBalanceMinor - debitAmountMinor < 0, returning HTTP 400 with error code INSUFFICIENT_FUNDS.
  3. 3
    Recharge Guardrails (disableAutoRecharge: true): Prevents automated reload triggers unless explicitly authorized by customer saved payment methods.
  4. 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

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

HTTP Response (200 OK)

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

Note: Counter staff can also debit or credit balances using POST /api/v1/scans (with x-scanner-key) or POST /api/v1/passes/:id/use / POST /api/v1/passes/:id/adjust-value (with Bearer/API Key auth), and audit transactions via GET /api/v1/balance-changes?passId=<passId>. Stored value rules support StoredValueOperation (NONE, ADD, SUBTRACT, SET) and StoredValueAmountSource (FIXED, OPERATOR, MECHANIC). Use externalId on 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/:token and poll payment status on GET /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.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.