El componente finora-checkout

El SDK @finora/checkout es un web component y una función, sin dependencias. Funciona en Chrome y Edge 90 o posterior, Safari 15 o posterior y Firefox 90 o posterior.

Instalación

Con un empaquetador:

npm i @finora/checkout

import { FinoraCheckout } from '@finora/checkout'; // al importarlo registra <finora-checkout>

Sin empaquetador, con la variable global FinoraCheckout:

<script src="https://pago.finoracore.com/sdk/finora-checkout.js"></script>

La etiqueta <finora-checkout>

<finora-checkout sesion="…" token="…" base-url="<URL_DEL_MERCHANT>"
                 tema="claro" idioma="es" teclado="auto" style="height: 40rem"></finora-checkout>

Atributos

Atributo	Valores	Por defecto	Para qué sirve
sesion	El sesionId	Obligatorio	La sesión que creó tu servidor
token	El token de cliente	Obligatorio	Solo vale para esa sesión y vence con ella
base-url	URL	El origen de la página	La URL del servidor de FINORA de tu ambiente
tema	claro, oscuro, auto	claro	auto sigue la preferencia del sistema
idioma	es, en	El del navegador	Textos del componente. Los nombres de los medios vienen del comercio
teclado	auto, siempre, nunca	auto	Teclado numérico en pantalla. auto lo muestra con pantalla táctil
modo	formal, inmersivo	formal	Presentación. Ver modo inmersivo
sonidos	Presente o ausente	Ausente	Sonidos suaves, solo en modo inmersivo

El componente ocupa la altura de su contenedor: dale height o min-height. Si cambias sesion o token, se vuelve a montar.

Eventos

Todos son CustomEvent, burbujean y atraviesan el shadow DOM.

Evento	detail	Cuándo
finora-sesion	La sesión: monto, comercio, medios	Al cargar. Útil para pintar tu propia cabecera
finora-rechazo	{ sesionId, riel, codigo, motivo, mensaje, intento, intentos }; motivo ya viene en palabras del cliente	Un intento se rechazó y la sesión sigue abierta
finora-resultado	{ sesionId, estado, riel, codigo, mensaje, autorizacion, recibo }	La sesión terminó
finora-cancelar	Ninguno	El cliente canceló
finora-error	{ codigo, mensaje }	Un error impide seguir, por ejemplo TOKEN_INVALIDO

estado es uno de APROBADA, RECHAZADA, EN_DUDA, CANCELADA o EXPIRADA. codigo es el código de respuesta del banco (00, 51…) o el motivo del cierre (CANCELADA_POR_CLIENTE).

Métodos y propiedades

Miembro	Qué hace
cancelar()	Cancela la sesión, como el botón «Cancelar». Con el terminal ya leyendo la tarjeta no procede y se sigue esperando
estado	Estado interno, de solo lectura. Sirve para depurar

FinoraCheckout.abrir(opciones)

const pago = FinoraCheckout.abrir({
  sesionId: '…',
  token: '…',
  baseUrl: '<URL_DEL_MERCHANT>',
  contenedor: '#pago',   // opcional: sin él, abre un modal
  tema: 'claro',
  idioma: 'es',
  teclado: 'auto',
  modo: 'formal',
  sonidos: false,
  onSesion: (sesion) => {},
  onRechazo: (intento) => {},
  onResultado: (resultado) => {},
  onCancelar: () => {},
  onError: (error) => {},
});

pago.elemento;   // el <finora-checkout> creado
pago.cancelar(); // cancela la sesión en el servidor
pago.cerrar();   // desmonta sin cancelar, por ejemplo después de onResultado

Como modal: capa con role="dialog", foco atrapado, desplazamiento de la página bloqueado y foco devuelto al cerrar. Escape cancela solo en los pasos de cédula, medios y datos, nunca con un cobro en vuelo. Después de onResultado el modal sigue mostrando el recibo hasta que llames a cerrar().

Reglas que el componente cumple siempre

• No existe un campo de tarjeta. Tarjeta significa «paga en el terminal».
• Un medio que no aplica se ve atenuado con su motivo; no se esconde.
• EN_DUDA no ofrece reintentar.
• La cuenta regresiva está siempre a la vista.

Accesibilidad

Un título por paso, anuncios en vivo durante la espera, errores con role="alert", campos con aria-invalid y su descripción, progreso con aria-current="step", contraste AA y respeto por la preferencia de reducir movimiento.