Banco simulado

1Qué es

Servicio que se comporta como el banco visto desde afuera para que el Merchant, la caja y el switch se prueben de punta a punta sin interconexión real. Existe porque el banco que aprobó la prueba del Merchant no puede darnos sus canales de pago móvil, crédito inmediato ni cripto antes de la demostración.

No es un mock: valida formatos, exige idempotencia, sabe quedarse en duda y responde a las consultas posteriores como lo haría un banco. Sus decisiones son deterministas y públicas: quien ensaya elige el desenlace con el monto o con el dato del pagador.

2Arquitectura

Dos caras

Cara	Puerto	Quién la usa	Contrato
HTTP autorizador	8095	Merchant (`AuthorizerClient`) para pago móvil, transferencia, QR y cripto	`POST /api/v1/autorizador/autorizaciones`, `GET …/{id}`, `POST …/{id}/reverso`
Host ISO 8583	9600 TCP	Switch Aurora (`IsoNodeClient`) para tarjetas emitidas por el banco	Layout `j8583.xml` del switch, EBCDIC Cp1047, bitmap binario, longitud de 2 bytes

Módulos: dominio (operación, libro en memoria, reglas y veredicto), api (contrato del autorizador y consola), iso (host Netty y autorizador de tarjetas). El libro es en memoria a propósito: el simulador se reinicia entre ensayos.

3Instalación y despliegue

./gradlew bootRun                      # http://localhost:8095  y  tcp 9600
./gradlew test                         # reglas, contrato HTTP y socket ISO real
docker buildx build --platform linux/amd64 -t git.dcgeeks.net/finora/banco-sim:prod-YYYYMMDD . --load
docker run -d --name finora-banco-sim --network finora_finora-net -p 8095:8095 -p 9600:9600 --restart unless-stopped git.dcgeeks.net/finora/banco-sim:prod-YYYYMMDD

Variables: SIM_HTTP_PUERTO, SIM_ISO_PUERTO, SIM_ISO_HABILITADO, SIM_LATENCIA_MS, SIM_DEMORA_DUDA_MS, SIM_TASA_VES_USDT, SIM_NOMBRE, SIM_CODIGO_BANCO.

4Operación diaria

La consola en / muestra el libro de operaciones en vivo, las reglas vigentes y el estado del host ISO. Antes de una demo: vaciar el libro (POST /api/v1/banco/operaciones/limpiar) y confirmar que el host ISO escucha.

Reglas

Canal	Condición	Desenlace
Todos	céntimos `.51` / `.05` / `.61`	51 Fondos insuficientes / 05 No honrar / 61 Excede el límite
Todos	céntimos `.96`	Aprobada, pero respondida tras 12 s: el cliente vence y queda EN DUDA; la consulta posterior confirma APROBADA
Todos	céntimos `.91`	503 y no se registra: la consulta posterior devuelve 404
Pago móvil	teléfono fuera de 0412/0414/0416/0424/0426 + 7 dígitos · termina en 0000	14 Teléfono inválido · 57 No afiliado
Transferencia	cuenta distinta de 20 dígitos · termina en 0000	14 Cuenta inválida · 62 Cuenta bloqueada
Cripto	wallet fuera de 20–64 alfanuméricos · cualquier otra	14 Wallet inválida · Aprobada con txHash y cotización USDT
Tarjeta ISO	PAN termina en 5100 / 1732 / 0018 / 5156 · 9999 · otro	51 / 43 / 54 / 41 · sin respuesta · 00 con código de autorización

5API e integraciones

Autorizar (el contrato que ya usa el Merchant)

POST /api/v1/autorizador/autorizaciones
{ "idOperacion": "PI-000123-1", "tipo": "COMPRA", "medio": "PAGO_MOVIL",
  "monto": 150.00, "moneda": "VES", "cuentaOrigen": "04141234567",
  "referenciaPago": "123456", "comercio": "900000000001", "terminal": "", "descripcion": "Venta 0042" }

200 { "aprobada": true, "codigo": "00", "mensaje": "Aprobada", "referenciaBanco": "PM000100001",
      "saldoDisponible": 4500.00, "banco": "Banco Simulado FINORA", "estado": "APROBADA" }

cuentaOrigen es el teléfono en pago móvil, la cuenta de 20 dígitos en transferencia, la wallet en cripto. referenciaPago es la clave C2P o la referencia del pago ya hecho; viaja y no se guarda.

Consultar y reversar

GET  /api/v1/autorizador/autorizaciones/{id}   → { estado: APROBADA|RECHAZADA|EN_PROCESO|REVERSADA, codigoRespuesta, mensaje, referenciaBanco }  (404 si nunca llegó)
POST /api/v1/autorizador/autorizaciones/{id}/reverso

Servicios del banco

GET  /api/v1/banco                      identidad y estado del host ISO
GET  /api/v1/banco/operaciones          libro (más recientes primero)
GET  /api/v1/banco/reglas               catálogo de reglas
GET  /api/v1/banco/pagomovil/p2c/verificar?referencia=&monto=&telefono=
GET  /api/v1/banco/cripto/cotizacion?activo=USDT&montoVes=

Cómo se conecta

Merchant: nodo BANCO_SIM en tba_authorizer_node con una ruta por medio en tba_authorizer_route (changelog 060-banco-simulado-y-rieles.xml). Para pasar al banco real basta cambiar base_url o crear otro nodo con menor prioridad.

Switch: dat_switch_node con protocolo ISO 8583 TCP, host finora-banco-sim, puerto 9600, framing LENGTH_PREFIX_2, y una tbl_bin_route por cada BIN del banco.

6Runbooks

Desplegar: construir la imagen amd64, transferirla al CT y arrancar el contenedor en la red finora_finora-net con el nombre finora-banco-sim (el Merchant lo resuelve por ese nombre).
Verificar: curl http://localhost:8095/api/v1/banco debe responder con isoHost.escuchando = true.
Ensayar una duda: cobrar un monto con céntimos .96; el Merchant marcará EN_DUDA y su barrido la resolverá como aprobada al consultar.
Rollback: parar el contenedor. El Merchant devolverá 91 en los medios que dependen de él; tarjeta no se ve afectada.

7Preguntas frecuentes

¿Guarda dinero o saldos? No. Cada operación es final en el momento y el saldo informado es simulado.

¿Firma o cifra? No hay MAC ni TLS: es un banco de laboratorio dentro de la red privada.

¿Qué pasa al reiniciarlo? El libro se vacía. Una operación en duda que el Merchant consulte después del reinicio recibirá 404 y se resolverá como no cobrada.