Aprende FINORA con ejemplos

1Una compra con tarjeta, de punta a punta

5 minutos

Lo que pasa por dentro

1. La caja le dice al terminal el monto (API ECR). El terminal lee la tarjeta: el PAN y el PIN nunca pasan por la caja.
2. El terminal llama al Merchant: POST /api/v1/pos/transacciones con su token de dispositivo. El Merchant comprueba que el TID sea suyo y resuelve la marca por el rango del PAN.
3. El Merchant arma un mensaje ISO 8583 0200 (solicitud de autorización) y se lo manda al Switch Aurora.
4. El switch mira el BIN (los primeros dígitos) y enruta: BIN 400000 al banco simulado, el resto al core. El emisor responde 0210 con un código de respuesta (RC).
5. Si RC = 00, la respuesta trae código de autorización y RRN; el Merchant captura la transacción en el lote abierto del terminal. Si no, la anota como rechazada y no entra al lote.

Ejemplo ejecutable

# 1) aprovisiona un dispositivo y guarda el deviceToken en $TOK
curl -s -X POST -H 'X-API-Key: pos-dev-key-2026' -H 'Content-Type: application/json' \
  -d '{"rif":"J123456789","serial":"APRENDE-01"}' http://localhost:9094/api/v1/pos/devices/activar

# 2) compra de 125,00 (montoCentavos: enteros, nunca decimales)
STAN=$(date +%H%M%S)
curl -s -X POST -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
  -d "{\"terminalId\":\"FIN00001\",\"tipo\":\"COMPRA\",\"montoCentavos\":12500,\"moneda\":\"928\",
       \"stan\":\"$STAN\",\"fechaHora\":\"$(date +%Y%m%d%H%M%S)\",\"modoEntrada\":\"051\",
       \"panEnmascarado\":\"541333******0010\",\"pan\":\"5413330000090010\",\"expiracion\":\"2812\",\"emv\":null}" \
  http://localhost:9094/api/v1/pos/transacciones
# → { "codigoRespuesta":"00", "codigoAutorizacion":"…", "rrn":"…", "numeroLote":…, "stan":… }

Después mira Transacciones → Transacciones adquirentes en http://localhost:9094: verás la fila con marca, producto, terminal y lote. Y en docker logs fn-finora-switch --tail 30, la decisión paso a paso.

Mini-quiz

2Pago móvil, transferencia y QR: los rieles que no son tarjeta

5 minutos

Lo que pasa por dentro

1. La caja abre una intención de pago en el Merchant (POST /api/v1/pagos/intenciones): «quiero cobrar 150,00 por la venta 0042». El Merchant responde qué rieles están habilitados y qué datos pide cada uno (cédula, teléfono, banco, referencia…).
2. La caja abre un intento por un riel: PAGO_MOVIL con el teléfono y el banco del cliente.
3. Para pago móvil, transferencia, QR y cripto el Merchant llama al autorizador del banco por HTTP (nodo BANCO_SIM en la demo). Para tarjeta, el intento se resuelve con la compra ISO de la lección 1.
4. El banco responde aprobada, rechazada o «en proceso». Si la respuesta vence, el intento queda EN_DUDA y un barrido lo consulta después.
5. Cuando lo cobrado cubre el monto, la intención pasa a PAGADA. Una intención puede tener varios intentos: uno rechazado y otro aprobado por otro riel.

Ejemplo ejecutable

POS=http://localhost:9094; KEY='X-API-Key: pos-dev-key-2026'
# 1) abrir la intención
curl -s -X POST $POS/api/v1/pagos/intenciones -H "$KEY" -H 'Content-Type: application/json' \
  -d '{"idempotencyKey":"venta-0042","merchantCode":"FIN000000000001","amount":150.00,"currency":"VES","description":"Venta 0042"}'
# → { "reference":"FNR…", "state":"CREADA", "rails":[{ "code":"PAGO_MOVIL", "campos":[{"code":"telefono",…}] }, …] }

# 2) abrir un intento por pago móvil (los datos del pagador según los campos que devolvió el riel)
curl -s -X POST $POS/api/v1/pagos/intenciones/FNR…/intentos -H "$KEY" -H 'Content-Type: application/json' \
  -d '{"railCode":"PAGO_MOVIL","amount":150.00,"datosPagador":{"cedula":"V12345678","telefono":"04141234567","banco":"0102"}}'

# 3) autorizar en línea contra el banco (secuencia 1)
curl -s -X POST $POS/api/v1/pagos/intenciones/FNR…/intentos/1/autorizar -H "$KEY" -H 'Content-Type: application/json' \
  -d '{"cuentaOrigen":"04141234567","payerBankCode":"0102","referenciaPago":"123456"}'
# → aprobada: intención PAGADA

Mini-quiz

3El lote y por qué se cierra

5 minutos

Lo que pasa por dentro

1. Cada terminal tiene un lote abierto a la vez (índice único ux_batch_open_por_terminal): al capturar la primera compra se abre solo.
2. Solo entran al lote las transacciones aprobadas (RC 00) y marcadas como capturadas. Las rechazadas y las caídas quedan registradas, pero fuera.
3. Al cerrar, el terminal manda un 0500 con el número de lote (DE 60) y sus totales (DE 63): cantidad y monto de ventas, cantidad y monto de devoluciones.
4. El Merchant compara esos totales con lo que él capturó. Coinciden → lote CLOSED. No coinciden → REJECTED: el problema queda visible, no escondido.
5. Un lote CLOSED es la unidad que la compensación va a tomar en la lección 4. Un lote abierto no se compensa nunca.

Ejemplo ejecutable

# Después de dos compras aprobadas de 125,00 y 87,30 en FIN00001 (lote $LOTE, lo devuelve cada compra en numeroLote)
curl -s -X POST -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
  -d '{"terminalId":"FIN00001","numeroLote":'"$LOTE"',
       "totales":{"cantidadVentas":2,"totalVentas":21230,"cantidadDevoluciones":0,"totalDevoluciones":0}}' \
  http://localhost:9094/api/v1/pos/lotes/cierre
# → RC 00 y el lote pasa a CLOSED. Míralo en Transacciones → Lotes.

Mini-quiz

4Compensación: contarle a la marca lo que pasó

5 minutos

Lo que pasa por dentro

1. La compensación (clearing) toma las transacciones elegibles: RC 00, capturadas, de un lote CLOSED y que no hayan sido compensadas antes.
2. Las agrupa por marca, porque cada marca habla un formato: Mastercard IPM (mensajes 1240 con función 200–205), Visa BASE II (TC05).
3. Escribe un archivo por marca y fecha/ciclo en clearing-out/ (p. ej. MA260702190568.ipm) y crea un registro por transacción con estado PRESENTED.
4. Cada registro recibe un ARN, la referencia que la marca y el emisor usarán para hablar de esa transacción en adelante (disputas incluidas).
5. Hoy el archivo es un formato lógico (texto delimitado) y no se transmite a la marca: sirve para el ciclo interno y para conciliar. El formato físico certificable y la transmisión son la fase de certificación con la marca.

Ejemplo ejecutable

# El ciclo completo (compensación → liquidación → conciliación) para hoy, ciclo 1. No hay botón en la UI.
curl -s -X POST -H 'X-API-Key: pos-dev-key-2026' \
  "http://localhost:9094/api/v1/pos/ops/ciclo?fecha=$(date +%F)&ciclo=1"
# → "clearing":[{"fileId":"MA…","marca":"MASTERCARD","formato":"IPM","mensajes":2,…}]
# Míralo en Compensación → Archivos de clearing y Registros de clearing.

Mini-quiz

5Liquidación: cuándo y cuánto cobra el comercio

5 minutos

Lo que pasa por dentro

1. Primero la posición: por institución, moneda y marca, cuánto se debe recibir o pagar en neto (crédito bruto − débito bruto − comisiones). Es el saldo entre bancos.
2. Luego la liquidación por comercio: se agrupan sus transacciones compensadas por moneda y canal y se aplica su regla (TbaSettlementRule): MDR en puntos básicos, interchange y plazo T+n.
3. Se aplican las retenciones (ISLR, IVA, IGTF) según TbaRetentionRule, con partición por instrumento cuando la norma lo exige.
4. Neto a pagar = bruto − MDR − interchange − retenciones, con fecha valor = fecha + n días hábiles. Se escribe un CSV en settlement-out/ (SETTLE…csv) y un registro DatMerchantSettlement.
5. Opcionalmente se postea al core (depósito al comercio, comisión del adquirente). Está detrás de dos banderas apagadas por defecto: pos.settlement.posting-enabled y merchant-posting-enabled. Encenderlas es una decisión, no un descuido.

Ejemplo con números

El comercio demo local tiene exactamente esa regla: MDR 250 bps y T+1. Ejecuta el ciclo (lección 4) y abre Liquidación → Liquidación por comercio: verás bruto, comisión, neto y fecha valor. El estado de cuenta (reporte MERCHANT_STATEMENT) se genera desde ese registro sin recalcular nada.

Mini-quiz

6Conciliación: cuadrar tres verdades

5 minutos

Lo que pasa por dentro

1. Nivel archivo: conteo, monto y checksum del archivo de compensación contra los registros PRESENTED de la base.
2. Nivel compensación: cada registro de clearing debe estar en un archivo conciliado.
3. Nivel liquidación: la posición neta calculada debe coincidir con el bruto de los registros que la componen.
4. Nivel transacción: cruce por ARN; si falta, por RRN + STAN + TID + monto. Acotado al día a propósito, para que una transacción de ayer no «empareje» con una de hoy.
5. Cada diferencia recibe un nombre: CAPTURED_NOT_CLEARED, CLEARED_NOT_CAPTURED, DUPLICATE_MATCH, AMOUNT_MISMATCH. El archivo del procesador (RECP…csv, con checksum) se concilia con el mismo motor.

Ejemplo ejecutable

# El mismo ciclo de la lección 4 termina en la conciliación
curl -s -X POST -H 'X-API-Key: pos-dev-key-2026' \
  "http://localhost:9094/api/v1/pos/ops/ciclo?fecha=$(date +%F)&ciclo=1"
# → "reconciliation": { … "status":"BALANCED" … }
# Míralo en Transacciones → Conciliación y excepciones.

Mini-quiz

7Cobro empujado: el motorizado que cobra sin tocar la caja

5 minutos

Lo que pasa por dentro

1. El sistema del comercio crea la intención con un bloque despacho y el TID del motorizado (POST /api/v1/pagos/intenciones, clave de API del comercio). Estado del despacho: PENDIENTE.
2. El terminal lleva una llamada abierta de hasta 25 s: GET /api/v1/pos/ordenes/pendiente?espera=25 (long-poll con su token). Cuando hay orden, la recibe y queda ENTREGADA con una reclamación atómica: dos sondeos nunca reciben la misma.
3. El terminal la acepta (ACEPTADA), muestra el monto y cobra con tarjeta exactamente como en la lección 1.
4. Reporta el veredicto (POST …/resultado): APROBADA → COMPLETADA y la intención PAGADA; RECHAZADA; EN_DUDA; o CANCELADA. Si nadie la toma en el TTL (300 s por defecto), un barrido la marca EXPIRADA y libera el terminal.
5. La venta se atribuye a la sucursal donde el terminal estaba asignado ese día (POST /api/v1/pagos/asignaciones), o a su sucursal fija si no hay asignación. Así el motorizado que hoy sale de la tienda Este suma en la tienda Este.

Ejemplo ejecutable

POS=http://localhost:9094; KEY='X-API-Key: pos-dev-key-2026'; TOKEN="Authorization: Bearer $TOK"
# comercio: asignar el terminal a la tienda de hoy y empujar la venta
curl -s -X POST $POS/api/v1/pagos/asignaciones -H "$KEY" -H 'Content-Type: application/json' \
  -d '{"terminalId":"FIN00001","storeCode":"0001","asignadoPor":"aprende"}'
curl -s -X POST $POS/api/v1/pagos/intenciones -H "$KEY" -H 'Content-Type: application/json' \
  -d '{"idempotencyKey":"ped-1","merchantCode":"FIN000000000001","amount":24.99,"currency":"VES",
       "description":"Pedido delivery","despacho":{"terminalId":"FIN00001","ttlSegundos":300}}'
# → "despacho":{"estado":"PENDIENTE","expiraEn":"…"}

# terminal (en otra consola): sondear, aceptar, reportar
curl -s -i "$POS/api/v1/pos/ordenes/pendiente?espera=25" -H "$TOKEN"       # 200 con la orden (204 si no hay)
curl -s -X POST $POS/api/v1/pos/ordenes/<referencia>/aceptar -H "$TOKEN"
curl -s -X POST $POS/api/v1/pos/ordenes/<referencia>/resultado -H "$TOKEN" -H 'Content-Type: application/json' \
  -d '{"estado":"APROBADA","codigoRespuesta":"00","autorizacion":"123456","panEnmascarado":"541333******0010","stan":"000123"}'
# → { "estado":"COMPLETADA", "estadoIntencion":"PAGADA" }

Mini-quiz

GGlosario en veinte términos

MID

Merchant ID. Identifica al comercio ante el adquirente y la marca. En FINORA, merchantCode.

TID

Terminal ID. Identifica al terminal (DE 41). El token del dispositivo lleva su TID; nunca viaja en el cuerpo.

BIN

Los primeros 6–8 dígitos del PAN. Dicen marca, emisor y producto; el switch enruta por BIN.

RC

Response code (DE 39). 00 aprobada; 51 fondos; 05 no honrar; 91 emisor inoperativo; 56 tarjeta no encontrada.

STAN

System Trace Audit Number (DE 11). Número de traza del terminal; se repite con el tiempo, por eso se cruza con fecha.

RRN

Retrieval Reference Number (DE 37). Referencia que asigna el adquirente/switch y que aparece en el recibo.

ARN

Acquirer Reference Number. Referencia que se asigna al compensar; con ella la marca y el emisor identifican la transacción en disputas.

Lote

Conjunto de transacciones aprobadas de un terminal entre dos cierres. Uno abierto a la vez; se cierra con 0500 y totales.

Clearing

Compensación: presentar a la marca las transacciones capturadas. Mueve información, no dinero.

Settlement

Liquidación: calcular y pagar el neto. Posición entre instituciones y liquidación por comercio.

MDR

Merchant Discount Rate. Comisión que paga el comercio sobre lo vendido, en puntos básicos (250 bps = 2,5 %).

Interchange

La parte del MDR que el adquirente le paga al emisor de la tarjeta, según tarifas de la marca.

T+1

Fecha valor: un día hábil después de la fecha de la transacción compensada. T+0, el mismo día.

EN_DUDA

No se sabe si se cobró (venció la espera). Nunca se reintenta con clave nueva: se consulta, se reversa o se concilia.

Reverso

Mensaje 0400/0420 que deshace una autorización. El switch exige el PAN (DE 2) y el MTI original en el DE 90.

Chargeback

Contracargo: el emisor devuelve una transacción por reclamo del tarjetahabiente. En FINORA: FIRST_CHARGEBACK → REPRESENTMENT → PRE_ARBITRATION → ARBITRATION.

ISO 8583

Estándar de mensajes de tarjeta: MTI (0200/0210, 0400/0410, 0500/0510) y campos DE numerados.

ISO 20022

Estándar de mensajería financiera en XML (pacs.008, pacs.002) que usa el Payment Hub para transferencias interbancarias.

Riel

Camino por el que se cobra una venta: TARJETA, PAGO_MOVIL, TRANSFERENCIA, QR, CRIPTO, EFECTIVO. Cada uno con reglas y campos propios.

Idempotencia

Repetir la misma petición con la misma clave produce el mismo resultado y ningún cobro extra. Es la defensa contra el doble cobro.