Descripción general
Las tarjetas de regalo, los pases de crédito en tienda y las billeteras prepago de circuito cerrado en Passinstance están respaldados por un libro mayor inmutable de partida doble (modelos prepaid account y prepaid ledger entry) en lugar de un campo de texto sin protección. Todos los importes monetarios se almacenan y calculan en unidades enteras mínimas de moneda (balanceMinor, como céntimos) con bloqueo estricto a nivel de fila e invariantes de saldo no negativo (disallowNegativeBalance: true).
Importante: Las deducciones de valor almacenado fallan de forma segura (fail closed) con
decision: "FAILED"yreasonCode: "OUT_OF_BALANCE"siempre que la deducción solicitada superebalanceMinoren una cuenta configurada condisallowNegativeBalance: true. Nunca calcule matemáticas de saldo en el cliente; envíe siempre el delta de la transacción y deje que el libro mayor del backend confirme el nuevo saldo.
Arquitectura del libro mayor de valor almacenado
Superficies de canje y ajuste de valor almacenado
Según su configuración física de caja o su flujo de consola de soporte, puede deducir o recargar saldos prepago a través de cuatro endpoints dedicados:
| Superficie | Endpoint | Autenticación | Caso de uso principal | |||||
|---|---|---|---|---|---|---|---|---|
| Escáner móvil / web | POST /api/v1/scans | x-scanner-key | Aplicación escáner del personal configurada con StoredValueOperation (`NONE | ADD | SUBTRACT | SET) y StoredValueAmountSource (FIXED | OPERATOR | MECHANIC`). |
| Lector NFC de hardware | POST /api/v1/reader/redeem | X-Reader-Secret | Orquestación servidor-a-lector que envía request payload (customerId, passId, amount, idempotencyKey). (Use POST /api/v1/reader/validate para verificación de códigos de barras de acceso.) | |||||
| Terminal POS de retail | POST /v1/pos/redeem | Terminal POS / Token Bearer | Cajas registradoras integradas que ejecutan PosOperation.DEDUCT_VALUE con passRef (serialNumber, código de barras o externalId) y clientTxRef. | |||||
| Panel / Recarga administrativa | POST /api/v1/passes/:id/adjust-value | JWT del espacio de trabajo / API Key (pass:manage) | Recargas manuales de tarjetas de regalo (action: "CREDIT"), reembolsos o correcciones administrativas (action: "DEBIT"). |
1. Débito mediante escáner de mostrador (POST /api/v1/scans)
Cuando una ScannerConfiguration utiliza StoredValueOperation.SUBTRACT y StoredValueAmountSource.OPERATOR, el cajero introduce el total de la compra y envía:
/api/v1/scans
{
"scannedBarcodeValue": "PI-GFT-901244",
"scannerConfigurationId": "scfg_giftcard_debit",
"validationData": {
"amount": 24.50,
"currency": "EUR"
},
"operatorId": "emp_cashier_04"
}
Respuesta (200 OK):
{
"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. Orquestación por lector de hardware (POST /api/v1/reader/redeem)
Las pasarelas de lectores ópticos y sin contacto del lado servidor se autentican mediante el encabezado X-Reader-Secret (reader integration secret) y envían request payload directamente a /api/v1/reader/redeem (cuando se omite amount, el motor realiza VALIDATE; cuando se incluye, ejecuta DEBIT):
/api/v1/reader/redeem
{
"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"
}
Respuesta (200 OK):
{
"success": true,
"resultingValue": "60.50"
}
3. Integración POS de retail (POST /v1/pos/redeem)
Los sistemas de punto de venta ejecutan deducciones atómicas mediante POST /v1/pos/redeem (montado bajo /v1/pos, fuera de /api/v1). passRef coincide con cualquier token de pase, código de barras, serialNumber o su externalId de origen:
{
"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"
}
Los valores soportados de PosOperation son DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID y CUSTOM. La respuesta devuelve walletPropagation (PosWalletPropagationStatus: QUEUED o SKIPPED) cuando se encolan actualizaciones push en vivo hacia APNs y Google Wallet.
4. Recargas manuales y correcciones (POST /api/v1/passes/:id/adjust-value)
Para reembolsos, créditos de atención al cliente o recargas de tarjetas de regalo desde el Panel de control o una integración ERP, llame a POST /api/v1/passes/:id/adjust-value con Idempotency-Key:
{
"action": "CREDIT",
"amount": "25.00",
"reason": "Customer return store credit",
"operatorId": "support_lead_02",
"idempotencyKey": "adj-20261116-0041"
}
Las acciones de ajuste soportadas son CREDIT (sumar saldo) y DEBIT (restar saldo).
Modelo de libro mayor de partida doble (prepaid account y prepaid ledger entry)
Cada pase de valor almacenado mantiene un registro prepaid account emparejado con filas de solo adición prepaid ledger entry:
| Campo | Modelo | Tipo | Descripción |
|---|---|---|---|
balanceMinor | prepaid account | Int | Saldo actual en unidades mínimas de moneda (por ejemplo, 7550 = €75.50). |
currency | prepaid account | String | Código de moneda ISO 4217 de 3 letras (EUR, USD, GBP, CHF). |
disallowNegativeBalance | prepaid account | Boolean | Por defecto true; exige balanceMinor >= 0 en la capa de transacción de base de datos. |
deltaMinor | prepaid ledger entry | Int | Cambio entero con signo (-2450 para débito, +5000 para recarga). |
balanceAfterMinor | prepaid ledger entry | Int | Instantánea de balanceMinor inmediatamente después del asiento. |
idempotencyKey | prepaid ledger entry | String | Clave única de transacción que evita débitos duplicados ante reintentos de red. |
Para auditar todos los débitos históricos, recargas y referencias de operadores, consulte GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger o GET /api/v1/balance-changes. Obtenga más información en Tarjetas de regalo y tarjetas prepago y Lectores NFC compatibles.
