Referencia del componente
Referencia de @finora/checkout 0.4.1, la versión que sirve https://pago.finoracore.com/sdk/finora-checkout.js y que usa la página alojada. Para empezar, mira primero Checkout web y app.
Hoy el SDK se carga con la etiqueta <script> desde el dominio de FINORA. La publicación del paquete en el registro público de npm está Próximamente; hasta entonces, los ejemplos con import aplican solo si FINORA te entregó el paquete.
<script src="https://pago.finoracore.com/sdk/finora-checkout.js"></script>
<!-- registra <finora-checkout> y el global FinoraCheckout -->
Atributos de <finora-checkout>
| Atributo | Valores | Por defecto | Qué hace |
|---|---|---|---|
sesion | id de sesión | obligatorio | La sesión que creó tu servidor. |
token | token de cliente | obligatorio | Solo sirve para esa sesión y vence con ella. |
base-url | URL | origen de la página | Raíz del Merchant: https://pos.finoracore.com. |
tema | claro · oscuro · auto | claro | auto sigue prefers-color-scheme. |
idioma | es · en | idioma del navegador | Textos del SDK. Los nombres de los medios vienen de la configuración del comercio. |
teclado | auto · siempre · nunca | auto | Teclado numérico en pantalla para cédula, teléfono y clave. auto: solo con puntero táctil (y siempre en modo inmersivo). |
modo | formal · inmersivo | formal | inmersivo: experiencia guiada para kioscos y tabletas. Ver Modos. |
sonidos | presente · false | apagado | Tonos sutiles al teclear, cambiar de paso y terminar. Solo en modo inmersivo. |
sin-cancelar | presente | ausente | Oculta los botones de cancelar: tu aplicación cancela desde su propia interfaz con cancelar(). |
El atributo pantalla lo usa la página alojada para no repetir lo que ya muestra su cabecera; no lo necesitas en tu página.
Cambiar sesion o token en caliente desmonta el componente y lo vuelve a montar. El componente llena la altura de su contenedor: dale height o min-height.
Métodos y propiedades del elemento
| Miembro | Qué hace |
|---|---|
cancelar() | Equivale a pulsar «Cancelar». Si el terminal ya aceptó la orden o el banco está respondiendo, no procede (COBRO_EN_CURSO): el componente muestra el aviso y sigue esperando. |
estado | Estado interno de solo lectura (paso actual, sesión, resultado). Útil para depurar o para decidir si Escape debe cancelar. |
FinoraCheckout.abrir(opciones)
| Opción | Tipo | Notas |
|---|---|---|
sesionId, token | string | Obligatorias. |
baseUrl | string | Raíz del Merchant. |
contenedor | elemento o selector | Si falta, se abre como modal. |
modal | boolean | Por defecto true cuando no hay contenedor. |
tema, idioma, teclado, modo, sonidos | Igual que los atributos. | |
onSesion(sesion) | función | La sesión se cargó: monto, comercio y medios. |
onResultado(resultado) | función | { sesionId, estado, riel, codigo, mensaje, autorizacion, recibo }. |
onCancelar() | función | El cliente canceló. |
onError({ codigo, mensaje }) | función | Error que impide seguir: TOKEN_INVALIDO, SESION_NO_ENCONTRADA o red al cargar. |
Devuelve una instancia con elemento (el <finora-checkout> montado), cancelar() (cancela en el servidor) y cerrar() (desmonta sin cancelar; úsalo tras onResultado).
const pago = FinoraCheckout.abrir({
sesionId, token, baseUrl: "https://pos.finoracore.com",
modo: "inmersivo", sonidos: true,
onResultado: (r) => {
// Solo experiencia: la entrega se decide con el webhook firmado.
mostrarGracias(r.estado);
setTimeout(() => pago.cerrar(), 4000);
},
});
Modos
formal (por defecto) | inmersivo | |
|---|---|---|
| Pensado para | Caja atendida e integraciones sobrias | Kiosco, autoservicio, tableta del cliente |
| Composición | Contenido con resumen lateral | Cabecera con el comercio, progreso de cuatro pasos (Carrito, Datos, Cobro, Recibo) y resumen de la compra |
| Tamaños | Texto base de 16 px; objetivos táctiles de 44 px o más | Texto base de 18 px; objetivos táctiles de 64 px o más |
| Teclado en pantalla | Solo con puntero táctil | Siempre en campos numéricos (teclado="nunca" lo apaga) |
| Movimiento y sonido | Ninguno | Transiciones breves; sonidos opcionales; se respeta prefers-reduced-motion |
Los dos modos usan la misma API, los mismos eventos y las mismas reglas: sin campo de tarjeta, EN_DUDA sin reintento y RECHAZADA final. En la página alojada se elige con ?modo=inmersivo:
https://pago.finoracore.com/s/{sesionId}?t={token}&modo=inmersivo
El monto siempre a la vista
Desde 0.4.1 el total a pagar es el elemento más destacado de cada paso, también en pantallas verticales: el cliente ve cuánto se le va a cobrar antes de presentar la tarjeta, mientras escribe la clave y en el resultado. Los bolívares se escriben Bs 1.234,56.
Medios que se cobran en el terminal
La tarjeta bancaria y la Tarjeta FINORA se cobran en un terminal físico: el componente no pide ningún dato de la tarjeta. El cliente acerca o inserta la tarjeta y escribe el PIN en el terminal. Si la sesión no tiene terminalId, esos medios aparecen atenuados con su motivo.
Durante la espera el componente consulta el estado de la sesión cada 2 segundos y muestra en qué paso está el terminal.
Tema
El componente vive en un shadow DOM: tu CSS no lo modifica. Personalízalo con las propiedades --fc-* descritas en Checkout web y app. El modo inmersivo deriva sus colores de esas mismas propiedades.
Compatibilidad
Chrome y Edge 90+, Safari 15+ y Firefox 90+. El SDK no carga fuentes, imágenes ni scripts de terceros: solo habla con base-url. Con una CSP estricta basta connect-src https://pos.finoracore.com.