11. Mobile money¶
← 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 |
| 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: Pago desde saldo móvil con red de agentes.
Modelo mental: El valor vive en una cuenta móvil y entra o sale mediante agentes o bancos.
Ejemplo concreto¶
Una persona envía el equivalente a $15.000 desde su wallet móvil a un comercio. El operador confirma y luego se cuadran saldos y comisión del agente.
Identifica wallet, cliente y agente. Operador valida PIN/OTP y mueve saldo.
Referencia del operador confirma el pago. Después: Saldos, comisiones y float de agentes se concilian.
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 wallet, cliente y agente. | ¿Existe una referencia propia, monto, moneda y expiración? |
| 2. Proceso | Operador valida PIN/OTP y mueve saldo. | ¿Qué sistema externo puede producir el efecto financiero? |
| 3. Confirmación | Referencia del operador confirma el pago. | ¿La evidencia viene de una API, webhook, banco o archivo autoritativo? |
| 4. Cierre | Saldos, comisiones y float de agentes se concilian. | ¿Ledger, proveedor y banco pueden explicar el mismo resultado? |
Qué ocurre si falla¶
Fallo característico: Falta de liquidez o reversa abre una excepción trazable.
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:
- Integrar cuenta/identidad del operador.
- Implementar cash-in, pago y cash-out idempotentes.
- Conciliar float de agentes y settlement.
Evidencia para considerarlo exitoso: Referencia del operador y saldos de cliente, agente y tesorería cuadrados.
Construcción concreta: Contrato operador + API/USSD + KYC + gestión de agentes y float.
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: ussd, sim-toolkit, app, agent-network
Operaciones cubiertas: cash-in, cash-out, p2p, merchant-payment, bill-pay
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 Mobile money 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.
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 Mobile money, 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.