API local de FINORA Pago

Referencia de la API local de FINORA Pago para Windows, transcrita de su documentación técnica y contrastada con las rutas del código de la versión 1.9. Para aprender a usarla, empieza por el tutorial Tu primer cobro desde tu sistema.

Reglas generales

Tema	Regla
Dirección	http://127.0.0.1:9810/v1/…. Solo escucha en el propio equipo (loopback): nadie de la red la ve. El puerto se cambia en Configuración
Autenticación	Si configuraste un token local, cada petición lo trae en X-Pago-Token: <token> o Authorization: Bearer <token>. Sin él: 401 TOKEN_LOCAL_INVALIDO
Formato	JSON en UTF-8. Los errores siempre tienen la forma {"codigo": "…", "mensaje": "…"}
CORS	Cerrado por defecto. Una caja que corre en un navegador del mismo equipo lo abre para su origen exacto (PAGO_CORS_ORIGENES=http://localhost:5173). Nunca uses *: cualquier página web podría pedir cobros
Una ventana a la vez	Un segundo cobro con ventana mientras hay otro en curso recibe 409 COBRO_EN_CURSO. Los cobros sin ventana pueden convivir

Rutas

Método y ruta	Para qué
GET /v1/salud	Estado de la aplicación, del comercio y de la conexión con FINORA Merchant
POST /v1/cobros	Crear un cobro
GET /v1/cobros/{cobroId}	Consultar un cobro; con ?esperar=1&plazo=60, esperar su veredicto
POST /v1/cobros/{cobroId}/cancelar	Cancelar un cobro en curso
GET /v1/cobros?desde=&hasta=&max=	Historial local (los últimos 5.000 cobros, el más reciente primero)
POST /v1/ventana/mostrar	Traer al frente la ventana del cobro en curso. Cuerpo: {"cobroId": "…"}
POST /v1/ventana/ocultar	Esconder la ventana sin cancelar nada

FINORA Pago tiene además dos rutas internas (/v1/actualizar y /v1/recargar-conf) que usa FINORA Toolbox para instalar versiones y recargar la configuración. Tu caja no las necesita.

GET /v1/salud

Responde aunque falte la configuración. Úsala al arrancar tu caja, no antes de cada cobro: merchantAlcanzable consulta a FINORA Merchant en ese momento y puede tardar hasta 15 segundos sin red.

Campo	Qué dice
version	Versión instalada de FINORA Pago
comercio	RIF, nombre y código del comercio configurado; null si falta configurar
merchantAlcanzable	true si FINORA Merchant respondió y aceptó la clave
ventanaAbierta, cobroEnCurso	Si hay una ventana de pago abierta y qué cobro atiende
puerto	Puerto de la API local
sandboxPorDefecto	Si los cobros que no dicen sandbox van al banco simulado
bloqueado	true si FINORA Merchant suspendió esta instalación; los cobros responden 503 TERMINAL_SUSPENDIDO
actualizacion	Si hay una versión nueva y en qué fase está (al-dia, descargando, lista…)

POST /v1/cobros

Cuerpo

Campo	Obligatorio	Qué es
monto	Sí	Mayor que 0, hasta 2 decimales. Acepta 227.50 o "227,50"
referencia	Sí	Tu pedido o factura, hasta 64 caracteres. Sin ella no hay forma de conciliar
moneda	No	Código ISO 4217. Por defecto, la del comercio
descripcion	No	Texto que se muestra en la ventana
items	No	Lista libre de productos, solo para mostrar
pagador	No	tipoDocumento, documento, nombre, telefono: precargan los campos del cliente
riel	Sin ventana, sí	TARJETA, PAGO_MOVIL, TRANSFERENCIA, QR o CRIPTO. Con ventana y sin riel, el cliente elige
campos	Según el riel	Los datos que pide ese medio (ver Medios y sus campos)
terminalId	Para TARJETA	El terminal físico al que se envía la tarjeta, si no hay uno configurado
tipoCuenta	No	Para tarjeta de débito: 10 ahorro, 20 corriente, 30 crédito (o AHORRO, CORRIENTE, CREDITO). Si la caja ya lo sabe, el terminal no lo vuelve a preguntar
mostrar	No	true abre la ventana de pago. Por defecto, lo configurado
modo	No	INMERSIVO (pantalla del cliente) o FORMAL (pantalla del cajero). Por defecto, lo configurado
esperar	No	true: la respuesta es el veredicto final y la llamada se bloquea hasta entonces
ttlSegundos	No	Plazo del cobro, de 60 a 3.600 segundos. Por defecto, 900
callbackUrl	No	Dirección de tu caja que recibe el aviso firmado al terminar
sandbox	No	true envía el cobro al banco simulado: sin dinero real

Respuesta

• 201, sin esperar: el cobro recién creado, en EN_CURSO, con su cobroId, su sesionId y urlPago (la página de pago alojada en pago.finoracore.com, por si quieres mostrarla como QR o abrirla en otro sitio).
• 200, con esperar: true: el cobro completo con su veredicto.

Campos principales del cobro:

Campo	Qué es
cobroId	Identificador del cobro en FINORA Pago. Guárdalo junto a la venta
estado	EN_CURSO, RECHAZO_PARCIAL, APROBADA, RECHAZADA, EN_DUDA, CANCELADA o EXPIRADA
codigo, mensaje	Código de respuesta del banco (00, 51, 05…) o un código técnico, y su texto
autorizacion	estado, codigo, referenciaBanco, autorizador y resueltoEn, tal como los dio el autorizador
recibo	Referencia FINORA, referencia del comercio, monto, moneda, medio, referencia del banco y fecha
intentos	Cada intento del cobro con su resultado. Un cobro aprobado al segundo intento trae dos
ultimoRechazo	Con RECHAZO_PARCIAL, el intento rechazado que el cliente está viendo
sandbox, mostrar, origen	Cómo se pidió el cobro (origen: api, uri o cli)
creadoEn, actualizadoEn, cerradoEn	Marcas de tiempo ISO 8601

Qué significa cada estado y qué debe hacer tu caja: Aprobado, en duda y rechazado.

GET /v1/cobros/{cobroId}

Devuelve el cobro tal como esté. Con ?esperar=1&plazo=60 espera hasta el veredicto o hasta plazo segundos. Vuelve antes si el cobro cambia a RECHAZO_PARCIAL (o regresa a EN_CURSO porque el cliente reintenta). Si vence el plazo sin veredicto, devuelve el cobro como esté: vuelve a preguntar.

Es la forma de recuperarte si se perdió la respuesta del POST, o de aclarar un cobro EN_DUDA.

POST /v1/cobros/{cobroId}/cancelar

Cancela el cobro en FINORA Merchant y lo devuelve como CANCELADA con codigo: CANCELADA_POR_COMERCIO. Responde 409 COBRO_EN_CURSO si el banco ya está respondiendo o el terminal ya aceptó la orden: en ese punto no se puede cancelar; espera el veredicto.

Aviso firmado a tu caja

Si el cobro trae callbackUrl, al terminar FINORA Pago le hace a esa dirección un POST con el mismo JSON del cobro y estas cabeceras:

Cabecera	Valor
X-Pago-Evento	pago.cobro
X-Pago-Cobro	El cobroId
X-Pago-Firma	sha256= seguido del HMAC-SHA256, en hexadecimal, del cuerpo crudo, con el token local como clave

• Sin token local configurado, la clave del HMAC es la cadena vacía.
• Reintenta tres veces (a los 0, 2 y 8 segundos). Responde 2xx rápido.
• Si tu caja estaba apagada, el veredicto sigue disponible en GET /v1/cobros/{cobroId}.

Cómo verificar la firma, con un vector de prueba: Verificar el aviso firmado.

Medios y sus campos

Los campos de cada medio los define FINORA Merchant para cada comercio. Estos son los del comercio de pruebas. La cédula puede ir en pagador.documento y pagador.tipoDocumento, o en campos.cedula.

riel	Campos	Notas
TARJETA	cedula	Necesita terminalId o un terminal configurado. La orden viaja al terminal físico y el cobro queda EN_CURSO hasta que el cliente paga allí o vence el plazo. El número de la tarjeta nunca pasa por tu caja ni por FINORA Pago
PAGO_MOVIL	cedula, telefono (0412, 0414, 0416, 0424 o 0426 más 7 dígitos), banco (código de 4 dígitos), clave (de 4 a 8 dígitos) y, opcional, referencia si el cliente ya pagó	La clave viaja al banco y no se guarda
TRANSFERENCIA	cedula, banco, cuenta (20 dígitos)
QR	cedula, telefono
CRIPTO	cedula, wallet (de 20 a 64 caracteres alfanuméricos)

Errores de la API

HTTP	codigo	Cuándo
400	PETICION_INVALIDA	Un campo no es válido: monto, referencia, riel, campos, modo, callbackUrl… El mensaje dice cuál
400	DATOS_INCOMPLETOS, MEDIO_NO_DISPONIBLE, TERMINAL_NO_ENCONTRADO…	FINORA Merchant rechazó el medio fijado. El cobro se cancela y te llega el motivo
401	TOKEN_LOCAL_INVALIDO	Falta X-Pago-Token o no coincide
404	COBRO_NO_ENCONTRADO, SIN_VENTANA, NO_ENCONTRADO	No existe ese cobro, esa ventana o esa ruta
405	METODO_NO_ADMITIDO	Método HTTP equivocado para la ruta
409	COBRO_EN_CURSO	Ya hay una ventana de cobro abierta (trae su cobroId), o el cobro no se puede cancelar todavía
503	MERCHANT_INALCANZABLE	No se llegó a FINORA Merchant o no respondió en 15 s. El cobro queda RECHAZADA con ese código
503	SIN_CONFIGURAR	Falta el RIF o la clave de API del comercio
503	TERMINAL_SUSPENDIDO	FINORA Merchant suspendió esta instalación

Códigos técnicos

Además de los códigos del banco, un cobro puede terminar con uno de estos motivos en codigo:

codigo	Qué pasó
MERCHANT_INALCANZABLE	No hubo conexión con FINORA Merchant
DATOS_INCOMPLETOS	Faltaron datos del medio de pago
MEDIO_NO_DISPONIBLE	El comercio no tiene activo ese medio
SESION_NO_ENCONTRADA	FINORA Merchant no reconoce la sesión de cobro
SIN_VEREDICTO	El cobro cerró sin una respuesta clara
CANCELADA_POR_COMERCIO	Lo canceló el cajero o tu caja
CANCELADA_POR_CLIENTE	Lo canceló el cliente en la ventana
TERMINAL_SIN_RESPUESTA	El terminal de tarjeta no respondió

Estado de esta página

Transcrita de la documentación técnica de FINORA Pago y contrastada con las rutas del código. Los ejemplos de respuesta de esta Academy usan el banco simulado; ninguno sale de un cobro con dinero real.