Skip to content
Help Center Guide · Redemption & Transactions
3 min readVerified 2026-11-16

Gift Card & Prepaid Balance Redemption

Deduct purchases, process prepaid reloads, enforce non-negative balance invariants, and inspect transaction ledger entries.

In This Guide

Overview

Gift cards, store credit passes, and closed-loop prepaid wallets in Passinstance are backed by an immutable double-entry ledger (prepaid account and prepaid ledger entry models) rather than an unguarded text field. All monetary amounts are stored and calculated in integer minor currency units (balanceMinor, such as cents) with strict row-level locking and non-negative balance invariants (disallowNegativeBalance: true).

Important: Stored-value deductions fail closed with decision: "FAILED" and reasonCode: "OUT_OF_BALANCE" whenever the requested deduction exceeds balanceMinor on an account configured with disallowNegativeBalance: true. Never compute balance math on the client; always submit the transaction delta and let the backend ledger commit the new balance.

Stored-Value Ledger Architecture

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
PREPAID LEDGER DEBIT & HARDWARE READER REDEMPTION
PARTICIPATING SYSTEM ACTORS
P1 Scanner / Hardware Reader
P2 Scan / Reader / POS Controller
P3 prepaid account & Ledger DB
STEP 1a REQUEST / ACTION POST/api/v1/scans
›
(StoredValueOp.SUBTRACT)
STEP 1b REQUEST / ACTION POST/api/v1/reader/redeem
STEP 2 REQUEST / ACTION SELECT ... FOR UPDATE
STEP 1c REQUEST / ACTION POST/v1/pos/redeem
›
(Lock prepaid account row)
›
(operation: DEDUCT_VALUE)
STEP 3 REQUEST / ACTION Check disallowNegativeBalance:
›
balanceMinor >= amountMinor
STEP 4 REQUEST / ACTION Insert prepaid ledger entry
›
& Update balanceMinor
STEP 5 RESPONSE 200 OK (remainingBalance)
STEP 6 REQUEST / ACTION Trigger APNs / Google Push

Stored-Value Redemption & Adjustment Surfaces

Depending on your physical checkout setup or support console workflow, you can deduct or reload prepaid balances across four dedicated endpoints:

SurfaceEndpointAuthenticationPrimary Use Case
Mobile / Web ScannerPOST /api/v1/scansx-scanner-keyStaff scanner app configured with StoredValueOperation (`NONEADDSUBTRACTSET) and StoredValueAmountSource (FIXEDOPERATORMECHANIC`).
Hardware NFC ReaderPOST /api/v1/reader/redeemX-Reader-SecretServer-to-reader orchestration submitting request payload (customerId, passId, amount, idempotencyKey). (Use POST /api/v1/reader/validate for barcode entry verification.)
Retail POS TerminalPOST /v1/pos/redeemPOS Terminal / Bearer TokenIntegrated cash registers executing PosOperation.DEDUCT_VALUE with passRef (serialNumber, barcode, or externalId) and clientTxRef.
Dashboard / Admin ReloadPOST /api/v1/passes/:id/adjust-valueWorkspace JWT / API Key (pass:manage)Manual gift card top-ups (action: "CREDIT"), refunds, or administrative corrections (action: "DEBIT").

1. Counter Scanner Debit (POST /api/v1/scans)

When a ScannerConfiguration uses StoredValueOperation.SUBTRACT and StoredValueAmountSource.OPERATOR, the cashier enters the purchase total and submits:

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

Response (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. Hardware Reader Orchestration (POST /api/v1/reader/redeem)

Server-side contactless and optical reader gateways authenticate using the X-Reader-Secret header (reader integration secret) and submit request payload directly to /api/v1/reader/redeem (when amount is omitted, the engine performs VALIDATE; when provided, it executes DEBIT):

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

Response (200 OK):

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

3. Retail POS Integration (POST /v1/pos/redeem)

Point-of-sale systems execute atomic deductions with POST /v1/pos/redeem (mounted under /v1/pos, outside /api/v1). passRef matches any pass token, barcode, serialNumber, or your upstream externalId:

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

Supported PosOperation values are DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, and CUSTOM. The response returns walletPropagation (PosWalletPropagationStatus: QUEUED or SKIPPED) when live push updates are queued to APNs/Google Wallet.

4. Manual Reloads & Corrections (POST /api/v1/passes/:id/adjust-value)

For refunds, customer service credits, or gift card reloads from the Dashboard or an ERP integration, call POST /api/v1/passes/:id/adjust-value with Idempotency-Key:

JSON
{
  "action": "CREDIT",
  "amount": "25.00",
  "reason": "Customer return store credit",
  "operatorId": "support_lead_02",
  "idempotencyKey": "adj-20261116-0041"
}

Supported adjustment actions are CREDIT (add balance) and DEBIT (subtract balance).

Double-Entry Ledger Model (prepaid account & prepaid ledger entry)

Every stored-value pass maintains a prepaid account record paired with append-only prepaid ledger entry rows:

FieldModelTypeDescription
balanceMinorprepaid accountIntCurrent balance in minor currency units (e.g., 7550 = €75.50).
currencyprepaid accountStringISO 4217 3-letter currency code (EUR, USD, GBP, CHF).
disallowNegativeBalanceprepaid accountBooleanDefaults to true; enforces balanceMinor >= 0 at the database transaction layer.
deltaMinorprepaid ledger entryIntSigned integer change (-2450 for debit, +5000 for reload).
balanceAfterMinorprepaid ledger entryIntSnapshot of balanceMinor immediately following the entry.
idempotencyKeyprepaid ledger entryStringUnique transaction key preventing duplicate debits on network retry.

To audit all historical debits, top-ups, and operator references, query GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger or GET /api/v1/balance-changes. Learn more in Gift Cards & Prepaid Cards and Compatible NFC Readers.

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.