10. Saldo almacenado y gift cards¶

← Volver a la tabla · Ver esta guía .md en GitHub

El mismo caso en tres formatos¶

Formato	Para qué sirve	Enlace
Markdown	Fuente única, revisable en GitHub.	Abrir fuente .md
HTML	Página generada automáticamente para navegar.	Abrir en GitHub Pages
PDF	Manual descargable; el índice lleva a este caso.	Abrir PDF en este caso

Los tres muestran el mismo catálogo. Markdown es la fuente; HTML y PDF son salidas generadas y verificadas.

En una frase¶

Sirve para: Gift card o saldo mantenido por el propio programa.

Modelo mental: El programa mantiene un saldo propio que debe reservarse y debitarse atómicamente.

Ejemplo concreto¶

Situación

Un cliente usa $8.000 de una gift card con saldo $10.000. El sistema reserva, captura y deja $2.000 sin permitir dos consumos simultáneos.

Detrás de la pantalla

Identifica cuenta y saldo disponible. Reserva atómica evita gastar dos veces.

Se acepta como pagado cuando

Captura consume saldo o libera la reserva. Después: Ledger demuestra saldo y pasivo del programa.

No confundas estas tres cosas¶

Lo que ocurre	Lo que significa	Lo que NO significa
El usuario vuelve a tu web	Terminó la experiencia del navegador	Que el dinero esté confirmado
El proveedor autoriza/confirma	Existe evidencia operativa del proveedor	Que el abono bancario ya esté conciliado
El reporte y el ledger cuadran	Puedes explicar el cierre financiero	Que nunca pueda existir devolución o disputa

Quién participa¶

Pagador
Canal o frontend
Backend del negocio
Proveedor o rail
Operaciones y conciliación

Recorrido completo, paso a paso¶

Etapa	Qué ocurre	Pregunta de control
1. Inicio	Identifica cuenta y saldo disponible.	¿Existe una referencia propia, monto, moneda y expiración?
2. Proceso	Reserva atómica evita gastar dos veces.	¿Qué sistema externo puede producir el efecto financiero?
3. Confirmación	Captura consume saldo o libera la reserva.	¿La evidencia viene de una API, webhook, banco o archivo autoritativo?
4. Cierre	Ledger demuestra saldo y pasivo del programa.	¿Ledger, proveedor y banco pueden explicar el mismo resultado?

flowchart LR A["Inicio Identifica cuenta y saldo disponible."] --> B["Proceso Reserva atómica evita gastar dos veces."] B --> C["Confirmar Captura consume saldo o libera la reserva."] C --> D["Cerrar Ledger demuestra saldo y pasivo del programa."] B -.-> U["Sin respuesta UNKNOWN"] U -.-> R["Consultar misma referencia no duplicar"] R -.-> C

Qué ocurre si falla¶

Fallo característico: Carrera o timeout se resuelve por idempotencia y reserva expirable.

Regla operativa: un timeout no equivale a rechazo. Conserva la operación como UNKNOWN, consulta mediante la misma referencia y permite un nuevo intento sólo cuando puedas demostrar que el anterior no produjo efecto.

Escenarios que debes probar:

Happy path con montos mínimos, normales y límites documentados.
Rechazo, cancelación del usuario, expiración y retorno del navegador manipulado.
Timeout antes y después de enviar, webhook tardío, duplicado y fuera de orden.
Refund total/parcial cuando aplique y conciliación con una diferencia intencional.
Prueba end-to-end en sandbox/certificación con credenciales separadas; producción solo después de aprobar el checklist.

Cómo llevarlo a una aplicación real¶

Primer incremento de desarrollo:

Modelar cuenta y reglas de expiración.
Reservar saldo con concurrencia segura.
Capturar, liberar o restituir mediante asientos.

Evidencia para considerarlo exitoso: Saldo anterior + movimientos = saldo nuevo, con journal balanceado.

Construcción concreta: API propia + PostgreSQL transaccional + ledger + reglas regulatorias.

Lenguaje, API y almacenamiento¶

Capa	Recomendación para este laboratorio	Responsabilidad
Frontend	TypeScript + HTML/CSS. El navegador presenta el checkout y recibe el retorno; no guarda secretos.	Experiencia; nunca secretos.
Backend	Python 3.11+ con FastAPI para este laboratorio. Node.js/TypeScript, Java, .NET o Go son equivalentes si el equipo los opera mejor.	Orden, autenticación, idempotencia y estados.
API/canal	HTTPS REST/JSON entre tu backend y el proveedor; webhooks HTTPS para cambios asíncronos.	Comunicar con proveedor o rail.
Datos	PostgreSQL para intents, eventos, idempotencia y ledger; Redis solo para cache/locks, nunca como libro contable.	Evidencia, ledger y auditoría.
Operación	Docker, gestor de secretos, logs estructurados, métricas, alertas y job de conciliación.	Despliegue, observabilidad y recuperación.

Tecnologías del catálogo: ledger, safeguarding, tokenization, qr, nfc

Operaciones cubiertas: e-money, closed-loop-wallet, prepaid-account, gift-card, store-credit, loyalty

Alta, contrato y costo¶

Dónde comenzar: Elegir un proveedor regulado que ofrezca esta modalidad en tu país, abrir cuenta comercial, verificar la empresa y solicitar sandbox.
Costo: El DEMO cuesta $0. Precio, impuestos, reservas y plazo de liquidación dependen del proveedor, país y volumen; pedir cotización vigente.
Decisión: Usa Saldo almacenado y gift cards solo si su cobertura, experiencia, reversibilidad y conciliación resuelven tu caso; compara al menos dos proveedores antes de LIVE.

Variables y callbacks¶

Variable	Obligatoria	Tratamiento	Propósito
`PAYLAB_HOST`	No	No secreta	Interfaz local. Solo se aceptan direcciones loopback.
`PAYLAB_PORT`	No	No secreta	Puerto del portal localhost.
`PAYLAB_CONFIG_DIR`	No	No secreta	Directorio alternativo para catálogo y guías.

Callbacks previstos:

No hay callback concreto hasta seleccionar un proveedor.

GitHub Pages nunca usa estas variables. Configúralas únicamente en localhost, CI protegido o el secret manager del backend.

Orden recomendado de implementación¶

Crear una orden/intención propia en el backend y fijar monto, moneda, comercio y expiración.
Enviar al proveedor desde el backend con credencial secreta e idempotency key; persistir referencia y request seguro.
Entregar al frontend solo el token, QR o URL de redirección de alcance mínimo.
Tratar el retorno del navegador como experiencia, no como prueba de pago; confirmar por API/webhook.
Validar y deduplicar el webhook, aplicar una máquina de estados monotónica y contabilizar una sola vez.
Consultar operaciones UNKNOWN y conciliar diariamente contra proveedor/banco; gestionar refunds y disputas.

Seguridad de datos¶

El monto, moneda, beneficiario y referencia nacen o se validan en el backend; nunca se confía en el navegador.
Secretos en un gestor de secretos, rotación y mínimo privilegio; jamás en JavaScript, Git o logs.
TLS, validación de firma/origen de webhooks, deduplicación persistente e idempotency key por operación.
Minimizar datos: almacenar tokens y referencias del proveedor, no PAN, CVV, claves ni credenciales bancarias.
Cifrado en reposo, control de acceso, trazabilidad y política de retención/borrado.

Ventajas y desventajas¶

Ventajas¶

Amplía las opciones de pago y desacopla el comercio de la red subyacente.

Desventajas¶

Disponibilidad, costos y reglas dependen del proveedor y la regulación local.

Aplicación vertical: moneda de videojuego¶

Una game currency reutiliza estas operaciones —load, reserve, debit, release, expiration y refund—, pero no se clasifica automáticamente como dinero electrónico. Debes analizar transferibilidad, convertibilidad, cash-out, emisor, aceptación y jurisdicción.

Objeto	Ejemplo	Evidencia
saldo	1.000 GEM	wallet + transaction history + journals
bien digital	SKIN_DRAGON	entitlement + inventory movement
pago externo	CLP 5.990	order + payment attempt + provider + settlement

Comprar GEM y gastar GEM son operaciones diferentes y usan órdenes e idempotency keys distintas. Ejecuta el recorrido en Economía virtual.

Checklist antes de LIVE¶

[ ] Contrato y cuenta comercial aprobados; costos y plazos confirmados directamente con el proveedor.
[ ] Credenciales productivas separadas, callbacks HTTPS públicos, dominios permitidos y rotación documentada.
[ ] Alertas, runbook, soporte, refund/disputa y conciliación ensayados con responsables definidos.
[ ] Piloto con límites y monitoreo reforzado; rollback que detiene nuevas operaciones sin perder evidencia.

Qué demuestra el DEMO y qué no¶

El DEMO permite observar el recorrido de Saldo almacenado y gift cards, incluyendo éxito, timeout recuperado, evento duplicado y diferencia de conciliación. No contacta al proveedor, no valida credenciales, no certifica cumplimiento y no mueve dinero.

Fuentes¶

Abrir Saldo almacenado y gift cards en la tabla · Configurar localhost