Tres formas de integrar tu caja

Tu sistema de caja sabe vender: arma el pedido, calcula el total, imprime la factura. Lo que no debería tener que saber es hablar con bancos, con terminales de tarjeta o con el servidor de adquirencia. Para eso está FINORA Pago: una aplicación que vive en la bandeja de Windows, junto al reloj, en el mismo equipo del mostrador.

La conversación es así de corta:

• Tu caja dice: «cobra 227,00 por el pedido 8841».
• FINORA Pago responde: «APROBADA, referencia del banco PM000100001».

Entre una frase y la otra, FINORA Pago crea el cobro en FINORA Merchant, le enseña al cliente una ventana para que elija cómo pagar (o no, si tu caja ya trae el medio), espera la respuesta y te la devuelve. Tu caja nunca toca el número de una tarjeta.

flowchart LR
    C["Tu sistema de caja<br/>ERP · caja propia · web local"] -->|"pide el cobro"| P["FINORA Pago<br/>en el mismo equipo"]
    P -->|"crea el cobro"| M["FINORA Merchant<br/>(la nube)"]
    M -->|"banco o terminal"| B["Medio de pago"]
    B -->|"veredicto"| M
    M -->|"estado"| P
    P -->|"APROBADA · RECHAZADA · EN DUDA"| C

Las tres puertas

Las tres llevan al mismo sitio y aceptan los mismos datos (monto, referencia, medio, si se abre la ventana…). Cambia cómo se pide el cobro y cómo vuelve la respuesta.

Puerta	Cómo la usa tu caja	Cómo recibe el veredicto	Para quién
API local	Una petición HTTP a http://127.0.0.1:9810/v1/cobros	En la misma respuesta, consultando después, o con un aviso firmado a tu caja	Cualquier lenguaje que haga HTTP: C#, Java, Node.js, Python, PowerShell, VB6 con WinHttp
Dirección finora-pago://	Abre una dirección, como si fuera una página: finora-pago://cobrar?monto=227.00&referencia=8841	No hay respuesta directa: llega por el aviso firmado o consultando la API local	Cajas que solo saben abrir un enlace o un documento (ShellExecute, start, un enlace en una intranet)
Programa finora-pago.exe	Ejecuta finora-pago.exe cobrar --monto 227.00 --referencia 8841 --json	En el código de salida del programa (0, 1, 2 o 3) y en el JSON que imprime	Cajas antiguas que saben lanzar un proceso y leer su código de retorno: Delphi, FoxPro, Clipper

API local: la más completa

Es la puerta principal. Solo escucha en 127.0.0.1, la dirección del propio equipo: nadie de la red local puede pedir cobros. Si configuras un token local, cada petición debe traerlo en la cabecera X-Pago-Token, y ese mismo token firma el aviso que FINORA Pago le manda a tu caja al terminar.

Tienes tres maneras de esperar el veredicto:

1. Esperar en la misma llamada ("esperar": true): la respuesta llega cuando el cobro termina. Es lo más simple.
2. Consultar GET /v1/cobros/{id}: sirve para recuperarte si se cortó la primera llamada.
3. Recibir un aviso en una dirección de tu caja (callbackUrl), firmado con HMAC-SHA256.

Dirección finora-pago://: la más sencilla

Al instalarse, FINORA Pago registra el esquema finora-pago:// en Windows. Si tu caja abre esa dirección, Windows le pasa el cobro a FINORA Pago (y lo abre si no estaba abierto). Es útil cuando no puedes hacer peticiones HTTP, pero tiene un límite claro: no devuelve nada. Para saber cómo terminó necesitas el aviso firmado o una consulta a la API local.

Programa finora-pago.exe: la más robusta para cajas viejas

Lanzas el ejecutable con argumentos y esperas a que termine. El veredicto viaja en el código de salida:

Código	Significa	Qué hace tu caja
0	Aprobada	Entrega la mercancía e imprime
1	Rechazada, cancelada o vencida	No entregues; ofrece otro medio
2	En duda	No entregues ni vuelvas a cobrar. Consulta más tarde
3	Error (datos inválidos, sin conexión, la aplicación no responde)	Revisa el mensaje y reintenta

Por qué un número y no un texto

Leer el texto de salida obliga a cada integrador a escribir su propio analizador, y ahí es donde una caja termina entregando mercancía porque encontró «aprobada» dentro de «no aprobada». El código de salida no se presta a esa confusión. El JSON que imprime el programa queda para el comprobante y la bitácora.

¿FINORA Pago o la API en la nube?

FINORA Pago es para la caja que corre en el mismo equipo de Windows del mostrador. Hay otros dos casos:

Tu situación	Qué usar
Tu caja está en el mismo equipo del mostrador y quieres una ventana de pago para el cliente, o mandar el medio ya elegido	FINORA Pago (esta sección)
Tu sistema es un servidor: un ERP central, una tienda en línea, un backend propio, y quieres avisos por webhook	La API de FINORA Checkout, con la clave de API del comercio
Tienes un terminal de pago en la red local y quieres hablarle directamente	El cobro empujado al terminal, que se explica en AuroraPOS

Lo que FINORA Pago no hace

• No guarda tarjetas ni ve números de tarjeta. La tarjeta se cobra en el terminal físico; tu caja y FINORA Pago solo reciben el resultado (monto, autorización, últimos cuatro dígitos).
• No habla ISO 8583 con los bancos ni decide por qué riel se cobra. Usa el mismo motor de cobro que FINORA Checkout: lo que se corrige allí queda corregido aquí.
• No sirve a otras máquinas. La API local es solo de ese equipo. Cada mostrador lleva su propio FINORA Pago; el comercio y la clave pueden ser los mismos.

Siguiente paso

• Haz tu primer cobro desde tu sistema, en modo de prueba.
• Entiende los veredictos: aprobado, en duda y rechazado.
• Consulta la referencia de la API local y la del programa y la dirección finora-pago://.