FINORA Pago para Windows: integra tu sistema de caja

1API local o API de nube

FINORA Pago no guarda tarjetas, no habla ISO 8583 y no decide rieles: crea una sesión de Checkout con la clave del comercio, abre (o no) una ventana con el widget oficial y te devuelve el veredicto. Lo que se corrija en el Checkout queda corregido aquí.

2Instalación

1. Ejecuta el instalador

   FINORA-Pago-1.0.0-win-x64.exe (NSIS, por máquina, pide permisos de administrador). Instala en C:\Program Files\FINORA Pago\, crea el acceso del menú Inicio y registra el esquema finora-pago://.

   certutil -hashfile FINORA-Pago-1.0.0-win-x64.exe SHA256

   Copiar

   Compara el resultado con el .sha256 publicado junto al instalador antes de instalar.

2. Configura RIF y clave

   Al terminar arranca sola y abre Configuración (PIN de fábrica 0000). Escribe el RIF, pega la clave de API y pulsa «Probar conexión».

3. Déjala en la bandeja

   Vive junto al reloj. Clic: Estado. Menú: Configuración, Salir (PIN). Datos en %APPDATA%\finora-pago\ (configuracion.json, historial.json, bitacora.log).

3Configuración

Todo se puede fijar también por variables de entorno, que mandan sobre la pantalla (imágenes de instalación, MDM): PAGO_MERCHANT_URL, PAGO_RIF, PAGO_API_KEY, PAGO_TERMINAL_ID, PAGO_PUERTO, PAGO_TOKEN_LOCAL, PAGO_MOSTRAR, PAGO_MODO_VENTANA, PAGO_MONITOR, PAGO_VENTANA_CAJERO, PAGO_SONIDOS, PAGO_COLOR_COMERCIO, PAGO_CIERRE_SEGUNDOS, PAGO_ARRANCAR_CON_WINDOWS, PAGO_SANDBOX, PAGO_CORS_ORIGENES.

Los dos modos de la ventana

4API local http://127.0.0.1:9810

• Solo loopback: nadie de la red la ve. Una caja en otra máquina usa la API de nube.
• Cabecera X-Pago-Token: <token> (o Authorization: Bearer) si configuraste el token. Sin él: 401 TOKEN_LOCAL_INVALIDO.
• JSON UTF-8. Los errores son siempre {"codigo": "...", "mensaje": "..."}.
• Sin CORS por defecto. Una caja en Chrome en la misma máquina lo habilita con PAGO_CORS_ORIGENES=http://localhost:5173 (nunca *: cualquier página web podría pedir cobros).

GET /v1/salud

curl -s http://127.0.0.1:9810/v1/salud

{"version":"1.0.0","comercio":{"rif":"J123456789","nombre":"Comercio Demo FINORA C.A.","merchantCode":"900000000001"},
 "terminal":null,"merchantAlcanzable":true,"ventanaAbierta":false,"cobroEnCurso":null,"puerto":9810,"sandboxPorDefecto":true}

merchantAlcanzable consulta al Merchant en el momento (hasta 15 s sin red): úsalo al arrancar tu caja, no antes de cada cobro.

POST /v1/cobros

{
  "monto": 227.00,                       // obligatorio, > 0, hasta 2 decimales ("227,50" también vale)
  "moneda": "VES",                       // opcional, ISO 4217; por defecto la del comercio
  "referencia": "8841",                  // obligatorio, hasta 64: tu pedido o factura
  "descripcion": "Pedido 8841",          // opcional, se muestra en la ventana
  "items": [{"nombre":"Cafe","cantidad":2,"precio":3.5}],   // opcional, JSON libre, solo se muestra
  "pagador": {"tipoDocumento":"V","documento":"12345678","nombre":"Ana","telefono":"04141234567"},
  "riel": "PAGO_MOVIL",                  // opcional: TARJETA · PAGO_MOVIL · TRANSFERENCIA · QR · CRIPTO
  "campos": {"telefono":"04141234567","banco":"0102","clave":"1234"},   // valores de los campos del riel
  "terminalId": "MOTO0001",              // para TARJETA si no hay terminal configurado
  "mostrar": true,                       // abre la ventana (por defecto: lo configurado)
  "modo": "INMERSIVO",                   // opcional: FORMAL | INMERSIVO; por defecto lo configurado
  "esperar": false,                      // true: la respuesta es el veredicto final (bloquea hasta el TTL)
  "ttlSegundos": 900,                    // 60..3600
  "callbackUrl": "http://127.0.0.1:5000/pago",   // POST firmado al terminar
  "sandbox": true                        // banco simulado, sin dinero real
}

• Con ventana (mostrar:true): sin riel, el cliente elige el medio en la ventana (widget oficial). Con riel + campos, se fija el medio y la ventana muestra la espera y el veredicto. modo decide la presentación de ese cobro (FORMAL compacto para el cajero, INMERSIVO a pantalla completa para el cliente).
• Sin ventana (mostrar:false): riel es obligatorio; los campos son los del riel (§7). Nadie ve nada; la aplicación orquesta y te responde.
• Una ventana a la vez: un segundo cobro con ventana mientras hay otro en curso recibe 409 COBRO_EN_CURSO con el cobroId del actual. Los silenciosos sí conviven; el Merchant protege el terminal (TERMINAL_OCUPADO).

Respuestas: 201 sin esperar ({"cobroId":"CB…","sesionId":"CS…","estado":"EN_CURSO","urlPago":"…"}; urlPago es la página alojada del Checkout, por si quieres enseñar un QR) o 200 con esperar:true: el cobro completo con veredicto. Salida literal de una prueba real contra pos.finoracore.com en sandbox:

{"cobroId":"CBf0Eu90y93C78","sesionId":"CS2XXRLh8KtYTm41g4EwZBjQ","estado":"APROBADA","monto":227,"moneda":null,
 "referencia":"PW-8841","descripcion":"Prueba FINORA Pago Windows","riel":"PAGO_MOVIL","codigo":"00","mensaje":"Aprobada",
 "autorizacion":{"estado":"APROBADO","codigo":"00","mensaje":null,"referenciaBanco":"PM000100001","autorizador":"BANCO_SIM","resueltoEn":"2026-09-13T15:32:59.685+00:00"},
 "recibo":{"referencia":"FNRMTZZ3THP","referenciaComercio":"PW-8841","monto":227,"moneda":"VES","comercio":"DEMO FINORA","riel":"PAGO_MOVIL",
           "referenciaBanco":"PM000100001","referenciaPagador":"04141234567","fecha":"2026-09-13T15:32:59.685+00:00"},
 "urlPago":null,"sandbox":true,"mostrar":false,"origen":"api","creadoEn":"2026-09-13T15:32:55.127Z","actualizadoEn":"2026-09-13T15:32:56.764Z","cerradoEn":"2026-09-13T15:32:56.764Z"}

Estados: EN_CURSO · APROBADA · RECHAZADA · EN_DUDA · CANCELADA · EXPIRADA. Los cinco últimos son finales.

codigo es el DE 39 del banco («00», «51», «05»…) o un motivo técnico: MERCHANT_INALCANZABLE, DATOS_INCOMPLETOS, MEDIO_NO_DISPONIBLE, SESION_NO_ENCONTRADA, SIN_VEREDICTO, CANCELADA_POR_COMERCIO, CANCELADA_POR_CLIENTE, TERMINAL_SIN_RESPUESTA.

Consulta, cancelación, historial, ventana

Callback firmado a tu caja

Si mandaste callbackUrl, al terminar el cobro FINORA Pago hace:

POST /pago HTTP/1.1
Content-Type: application/json
User-Agent: FINORA-Pago-Callback/1.0
X-Pago-Evento: pago.cobro
X-Pago-Cobro: CBf0Eu90y93C78
X-Pago-Firma: sha256=f44ebc9873f965313dadb3804003d9cbccec91f515342aee3fa20bf4ad33b396

{"evento":"pago.cobro","cobroId":"CBf0Eu90y93C78","estado":"APROBADA", …el mismo JSON del cobro… }

• Firma: sha256=hex(HMAC-SHA256(tokenLocal, cuerpo crudo)). Verifica sobre los bytes que recibiste, no sobre el JSON reparseado. Sin token configurado, la clave del HMAC es la cadena vacía.
• Reintentos: 3 (0 s, 2 s, 8 s). Responde 2xx rápido. Si tu caja estaba caída, el veredicto sigue en GET /v1/cobros/{id}.
• Vector de prueba: token secreto, cuerpo {"a":1}. Si tu HMAC no coincide, estás firmando otra cosa (espacios, reparseo).

Códigos de error

5URI finora-pago://

Para cajas que solo saben abrir una URL (ShellExecute, start, un enlace en una intranet). Mismos parámetros que POST /v1/cobros; los campos del riel como campo.<code>= y el pagador como pagador.<campo>=. callback = callbackUrl, ttl = ttlSegundos.

start "" "finora-pago://cobrar?monto=227.00&referencia=8841&callback=http%3A%2F%2F127.0.0.1%3A5000%2Fpago"

start "" "finora-pago://cobrar?monto=227.00&referencia=8841&mostrar=false&riel=PAGO_MOVIL&campo.telefono=04141234567&campo.banco=0102&campo.clave=1234&pagador.documento=12345678&pagador.tipoDocumento=V&sandbox=true"

start "" "finora-pago://cobrar?monto=64.90&referencia=8842&modo=formal&callback=http%3A%2F%2F127.0.0.1%3A5000%2Fpago"

6CLI finora-pago.exe

finora-pago.exe cobrar --monto 227.00 --referencia 8841 --json
finora-pago.exe cobrar --monto 64.90 --referencia 8842 --modo formal --json
finora-pago.exe cobrar --monto 227.00 --referencia 8841 --mostrar false --riel PAGO_MOVIL --campo-telefono 04141234567 --campo-banco 0102 --campo-clave 1234 --pagador-documento 12345678 --pagador-tipoDocumento V --sandbox true --json
finora-pago.exe cobrar --monto 15.00 --referencia 8843 --mostrar false --riel TARJETA --terminalId MOTO0001 --json
finora-pago.exe consultar CBf0Eu90y93C78 --esperar --json
finora-pago.exe cancelar CBf0Eu90y93C78 --json
finora-pago.exe salud --json

• Siempre espera el veredicto e imprime el JSON del cobro (o {"error":{codigo,mensaje}}).
• Códigos de salida: 0 aprobada · 1 rechazada, cancelada o expirada · 2 en duda · 3 error.
• Si FINORA Pago no está abierta, la CLI la lanza en segundo plano y espera hasta 20 s a que responda.
• Lee puerto y token de %APPDATA%\finora-pago\configuracion.json; también PAGO_PUERTO y PAGO_TOKEN_LOCAL por entorno.

Salida literal de una prueba real (sandbox):

> finora-pago cobrar --monto 5.05 --referencia CLI-02 --mostrar false --riel PAGO_MOVIL --campo-telefono 04141234567 --campo-clave 1234 --campo-banco 0102 --pagador-documento 12345678
RECHAZADA CBCgGq0WBJw1Tf CLI-02 5.05 [05] ref FNRMTZZ6XMX-1
exit=1

7Rieles y campos

Los campos los define el Merchant por riel (back-office); estos son los del comercio de pruebas hoy. La cédula puede ir en pagador.documento + pagador.tipoDocumento o en campos.cedula.

8Sandbox

"sandbox": true (o «Sandbox por defecto») manda el cobro al banco simulado de FINORA: sin dinero real, con reglas públicas por céntimos del monto.

Pago móvil: teléfono fuera del patrón → 14; termina en 0000 → 57. Tarjeta (en el terminal): PAN terminado en 5100 / 1732 / 0018 / 5156 → 51 / 43 / 54 / 41; en 9999 → sin respuesta (EN_DUDA). Tabla completa en Banco simulado.

9Ejemplos

Todos hacen lo mismo: POST /v1/cobros con esperar:true y deciden por estado. Los ejemplos completos (caja Express con callback, consola .NET 8) están en merchant/finora-pago-windows/examples/.

C# / .NET

using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("http://127.0.0.1:9810") };
http.DefaultRequestHeaders.Add("X-Pago-Token", Environment.GetEnvironmentVariable("PAGO_TOKEN") ?? "");

var respuesta = await http.PostAsJsonAsync("/v1/cobros", new {
    monto = 227.00m, referencia = "8841", descripcion = "Pedido 8841",
    mostrar = true, esperar = true, sandbox = true
});
var cobro = await respuesta.Content.ReadFromJsonAsync<Cobro>();
if (!respuesta.IsSuccessStatusCode) { Console.WriteLine($"{cobro?.codigo}: {cobro?.mensaje}"); return; }
switch (cobro!.estado) {
    case "APROBADA": MarcarPagado(cobro.referencia, cobro.autorizacion?.referenciaBanco); break;
    case "EN_DUDA":  BloquearEntrega(cobro.cobroId); break;   // no vuelvas a cobrar
    default:         Console.WriteLine($"No pagado: {cobro.estado} {cobro.codigo}"); break;
}

record Autorizacion(string? codigo, string? referenciaBanco);
record Cobro(string cobroId, string estado, string referencia, string? codigo, string? mensaje, Autorizacion? autorizacion);

Alternativa sin HTTP, lanzando el ejecutable y leyendo JSON de stdout:

var psi = new System.Diagnostics.ProcessStartInfo(@"C:\Program Files\FINORA Pago\finora-pago.exe",
    "cobrar --monto 227.00 --referencia 8841 --json") { RedirectStandardOutput = true, UseShellExecute = false, CreateNoWindow = true };
using var p = System.Diagnostics.Process.Start(psi)!;
string json = await p.StandardOutput.ReadToEndAsync();
await p.WaitForExitAsync();
// p.ExitCode: 0 aprobada · 1 rechazada/cancelada/expirada · 2 en duda · 3 error

Java

var http = java.net.http.HttpClient.newHttpClient();
var cuerpo = """
  {"monto":227.00,"referencia":"8841","mostrar":true,"esperar":true,"sandbox":true}""";
var req = java.net.http.HttpRequest.newBuilder(java.net.URI.create("http://127.0.0.1:9810/v1/cobros"))
    .header("Content-Type", "application/json").header("X-Pago-Token", System.getenv().getOrDefault("PAGO_TOKEN", ""))
    .timeout(java.time.Duration.ofSeconds(930))
    .POST(java.net.http.HttpRequest.BodyPublishers.ofString(cuerpo)).build();
var res = http.send(req, java.net.http.HttpResponse.BodyHandlers.ofString());
var json = new com.fasterxml.jackson.databind.ObjectMapper().readTree(res.body());
if (res.statusCode() == 200 && "APROBADA".equals(json.get("estado").asText())) {
    marcarPagado("8841", json.path("autorizacion").path("referenciaBanco").asText());
}

Node.js

const r = await fetch("http://127.0.0.1:9810/v1/cobros", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Pago-Token": process.env.PAGO_TOKEN ?? "" },
  body: JSON.stringify({ monto: 227.0, referencia: "8841", mostrar: true, esperar: true, sandbox: true }),
});
const cobro = await r.json();
if (r.ok && cobro.estado === "APROBADA") marcarPagado(cobro.referencia, cobro.autorizacion?.referenciaBanco);

Verificar el callback (Express):

import { createHmac, timingSafeEqual } from "node:crypto";
app.post("/pago", express.raw({ type: "application/json" }), (req, res) => {
  const esperada = Buffer.from("sha256=" + createHmac("sha256", process.env.PAGO_TOKEN ?? "").update(req.body).digest("hex"));
  const recibida = Buffer.from(req.get("X-Pago-Firma") ?? "");
  if (esperada.length !== recibida.length || !timingSafeEqual(esperada, recibida)) return res.sendStatus(401);
  const cobro = JSON.parse(req.body.toString("utf8"));
  if (cobro.estado === "APROBADA") marcarPagado(cobro.referencia);
  res.sendStatus(200);
});

Python

import os, requests
r = requests.post("http://127.0.0.1:9810/v1/cobros",
    json={"monto": 227.00, "referencia": "8841", "mostrar": True, "esperar": True, "sandbox": True},
    headers={"X-Pago-Token": os.environ.get("PAGO_TOKEN", "")}, timeout=930)
cobro = r.json()
if r.ok and cobro["estado"] == "APROBADA":
    marcar_pagado(cobro["referencia"], cobro["autorizacion"]["referenciaBanco"])
elif cobro.get("estado") == "EN_DUDA":
    bloquear_entrega(cobro["cobroId"])

PowerShell

$cuerpo = @{ monto = 227.00; referencia = "8841"; mostrar = $true; esperar = $true; sandbox = $true } | ConvertTo-Json
$cobro = Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:9810/v1/cobros" -ContentType "application/json" -Body $cuerpo -Headers @{ "X-Pago-Token" = $env:PAGO_TOKEN } -TimeoutSec 930
if ($cobro.estado -eq "APROBADA") { "Pagado: $($cobro.autorizacion.referenciaBanco)" } else { "No pagado: $($cobro.estado) $($cobro.codigo)" }

# O con el ejecutable:
& "C:\Program Files\FINORA Pago\finora-pago.exe" cobrar --monto 227.00 --referencia 8841 --json | ConvertFrom-Json
$LASTEXITCODE   # 0 aprobada · 1 rechazada · 2 en duda · 3 error

VB6 / COM (WinHttp)

Dim http As Object
Set http = CreateObject("WinHttp.WinHttpRequest.5.1")
http.SetTimeouts 5000, 5000, 5000, 930000
http.Open "POST", "http://127.0.0.1:9810/v1/cobros", False
http.SetRequestHeader "Content-Type", "application/json"
http.SetRequestHeader "X-Pago-Token", TOKEN_LOCAL
http.Send "{""monto"":227.00,""referencia"":""8841"",""mostrar"":true,""esperar"":true}"
If http.Status = 200 Then
    If InStr(http.ResponseText, """estado"":""APROBADA""") > 0 Then
        MarcarPagado "8841"
    End If
End If

O sin HTTP, ejecutando finora-pago.exe cobrar … --json con la salida redirigida a un archivo y leyéndolo:

Shell "cmd /c ""C:\Program Files\FINORA Pago\finora-pago.exe"" cobrar --monto 227.00 --referencia 8841 --json > C:\caja\ultimo-cobro.json", vbHide
' espera a que el archivo exista y léelo; el JSON trae "estado" y "codigo"

10Diagnóstico

• Bandeja → Estado: salud de la API local y del Merchant, últimos cobros con su código, y la bitácora con códigos cortos (M-3F2A) que se dictan por teléfono.
• %APPDATA%\finora-pago\bitacora.log: una línea JSON por evento; rota a 5 MB.
• GET /v1/salud responde aunque falte la configuración: comercio: null y merchantAlcanzable: false.
• 401 TOKEN_LOCAL_INVALIDO: la caja no manda el token que está en Configuración. Genera uno nuevo, cópialo a la caja y guarda.
• 409 COBRO_EN_CURSO: hay una ventana abierta con otro cobro. Ciérrala con OK, espera el cierre automático o cancela por API.
• 503 MERCHANT_INALCANZABLE: sin internet o Merchant caído; revisa «Probar conexión».
• «El puerto 9810 ya está en uso»: hay otra instancia (mira la bandeja) o cambia el puerto.
• La ventana no se ve en pantalla completa: apaga «Pantalla completa» para probar en un escritorio; en el mostrador vuelve a encenderla.

11Preguntas frecuentes