Cómo funciona una sesión de cobro

FINORA Checkout cobra en línea con la misma lógica que una caja del comercio: el cliente elige cómo pagar, FINORA pide los datos que ese medio necesita, autoriza con el banco y devuelve un veredicto. La diferencia es que todo ocurre en un navegador que no controlas. Por eso el diseño reparte la confianza en tres credenciales, cada una con un alcance mínimo.

Tres credenciales, tres trabajos

Credencial	Quién la tiene	Qué puede hacer	Qué no puede hacer
Clave API del comercio	Solo tu servidor	Crear, consultar, listar y cancelar sesiones	Nada desde el navegador: allí no debe existir
Token de cliente	El navegador, para una sesión	Ver esa sesión, elegir medio, enviar los datos del pago, consultar el estado	Crear sesiones, cambiar el monto, ver otra sesión. Vence con su sesión
Secreto del webhook	Solo tu servidor	Verificar que un aviso viene de FINORA	Nada más: no autentica llamadas

La regla que sale de esta tabla es corta: lo que viaja al navegador no sirve para robar. Si alguien copia el token, como mucho puede pagar ese pedido por ese monto.

La sesión es un pedido con fecha de vencimiento

Una sesión de cobro guarda lo mínimo: el monto, la moneda, la referencia de tu pedido, los medios disponibles y hasta cuándo vale. Por defecto vence a los 15 minutos; puedes fijar entre 1 y 60 minutos con ttlSegundos. El cliente ve la cuenta regresiva todo el tiempo.

Por dentro, cada sesión es una intención de pago del Merchant, la misma pieza que usan las cajas y los terminales. Cada vez que el cliente intenta pagar, se abre un intento dentro de esa intención, y cada intento termina en un veredicto. Si quieres el detalle, está en Intención, intento y veredicto.

flowchart TB
    T[Tu servidor] -- "clave API" --> S[(Sesión de cobro)]
    S -- "sesionId + token" --> N[Navegador del cliente]
    N -- "medio y datos del pago" --> S
    S --> I[Intento de cobro]
    I -- "pago móvil, transferencia, QR" --> B[Banco]
    I -- "tarjeta" --> P[Terminal del comercio]
    B --> V{Veredicto}
    P --> V
    V -- "aviso firmado" --> T

Tu página nunca ve una tarjeta

El checkout no tiene ningún campo para el número de tarjeta, la fecha ni el código de seguridad. Cuando el cliente elige tarjeta, FINORA envía la orden de cobro a un terminal físico de tu comercio (el que indicaste con terminalId), y la tarjeta se lee allí, con chip y PIN. A tu página solo vuelve el número enmascarado del recibo, del tipo 4111 11•• •••• 1111.

Las claves de pago móvil siguen el mismo principio: van del navegador del cliente al banco a través de FINORA y no se guardan en ningún sitio.

Lo que sí es tuyo cuidar

La clave API y el secreto del webhook. Guárdalos como guardas la contraseña de tu base de datos: en variables de entorno del servidor, fuera del repositorio y fuera del código que descarga el navegador. Si sospechas que se filtraron, genera otros desde el Portal del comercio.

Esto reduce mucho lo que tu tienda tiene que proteger, pero no reemplaza la evaluación de seguridad que te pida tu adquirente: esa la define él para tu caso.

El aviso firmado es la verdad

El navegador cuenta el final de la historia dos veces: con el evento onResultado del componente y con la vuelta a tu returnUrl. Ninguna de las dos es prueba de pago, porque ambas ocurren en una máquina que no controlas.

La prueba es el webhook: un POST que FINORA firma con HMAC-SHA256 usando tu secreto, con la hora del envío dentro de la firma para que un aviso viejo no se pueda reenviar. Tu servidor lo verifica y solo entonces entrega el pedido. Si el aviso no llega, tu servidor puede preguntar con su clave API: GET /api/v1/checkout/sesiones/{id} siempre responde el estado real.

Los medios los decide el comercio, no tu página

Qué medios aparecen, con qué nombre, qué campos piden y con qué montos mínimos y máximos lo define la configuración de tu comercio en FINORA. El checkout pinta lo que recibe:

• Un medio que no aplica a este pedido se ve atenuado con su motivo (por ejemplo, «Mínimo Bs 500,00»), en lugar de desaparecer.
• La tarjeta solo aparece disponible si la sesión tiene un terminal.
• El efectivo nunca aparece en la web: nadie puede entregar billetes a una página.
• Un medio nuevo aparece sin que tengas que actualizar tu integración.

Dónde sigue

• Los estados de una sesión, incluido qué hacer con EN_DUDA.
• Integra FINORA Checkout en 10 minutos, para verlo funcionar.