Skip to content
Guía del Centro de ayuda · Canjes y transacciones
4 min de lecturaVerificado 2026-11-16

Canje de saldo en tarjetas regalo

Descuenta importes, realiza recargas prepago, evita saldos negativos y revisa el historial contable.

En esta guía

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" y reasonCode: "OUT_OF_BALANCE" siempre que la deducción solicitada supere balanceMinor en una cuenta configurada con disallowNegativeBalance: 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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
DÉBITO EN LIBRO MAYOR PREPAGO Y CANJE POR LECTOR DE HARDWARE
ACTORES DEL SISTEMA
P1 Escáner / Lector de hardware
P2 Controlador Scan / Reader / POS
P3 BD prepaid account y Ledger
PASO 1a SOLICITUD / ACCIÓN POST/api/v1/scans
›
(StoredValueOp.SUBTRACT)
PASO 1b SOLICITUD / ACCIÓN POST/api/v1/reader/redeem
PASO 2 SOLICITUD / ACCIÓN SELECT ... FOR UPDATE
PASO 1c SOLICITUD / ACCIÓN POST/v1/pos/redeem
›
(Bloqueo fila prepaid account)
›
(operation: DEDUCT_VALUE)
PASO 3 SOLICITUD / ACCIÓN Comprobar disallowNegativeBalance:
›
balanceMinor >= amountMinor
PASO 4 SOLICITUD / ACCIÓN Insertar prepaid ledger entry
›
y actualizar balanceMinor
PASO 5 RESPUESTA 200 OK (remainingBalance)
PASO 6 SOLICITUD / ACCIÓN Enviar push APNs / Google

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:

SuperficieEndpointAutenticaciónCaso de uso principal
Escáner móvil / webPOST /api/v1/scansx-scanner-keyAplicación escáner del personal configurada con StoredValueOperation (`NONEADDSUBTRACTSET) y StoredValueAmountSource (FIXEDOPERATORMECHANIC`).
Lector NFC de hardwarePOST /api/v1/reader/redeemX-Reader-SecretOrquestació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 retailPOST /v1/pos/redeemTerminal POS / Token BearerCajas registradoras integradas que ejecutan PosOperation.DEDUCT_VALUE con passRef (serialNumber, código de barras o externalId) y clientTxRef.
Panel / Recarga administrativaPOST /api/v1/passes/:id/adjust-valueJWT 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:

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

Respuesta (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. 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):

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

Respuesta (200 OK):

JSON
{
  "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:

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

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:

JSON
{
  "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:

CampoModeloTipoDescripción
balanceMinorprepaid accountIntSaldo actual en unidades mínimas de moneda (por ejemplo, 7550 = €75.50).
currencyprepaid accountStringCódigo de moneda ISO 4217 de 3 letras (EUR, USD, GBP, CHF).
disallowNegativeBalanceprepaid accountBooleanPor defecto true; exige balanceMinor >= 0 en la capa de transacción de base de datos.
deltaMinorprepaid ledger entryIntCambio entero con signo (-2450 para débito, +5000 para recarga).
balanceAfterMinorprepaid ledger entryIntInstantánea de balanceMinor inmediatamente después del asiento.
idempotencyKeyprepaid ledger entryStringClave ú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.

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.