Solo kiosco Android. POS, web e iOS no usan este paquete.
Sigue las secciones de abajo para integrarlo a mano. Para dárselo a un agente, copia el prompt de Prompt para un agente.
Requisitos
- Un kiosco Android con el pinpad por USB.
- Un development build. Expo Go no carga el módulo nativo.
- Los binarios de CliSiTef de ese entorno (homologación o producción), de Software Express. Guárdalos fuera de git.
Activarlo
- En el dashboard, abre tu comercio, ve a Payments y crea un pago con el proveedor CliSiTef y el método PIN pad.
- En Connection Settings, completa:
- En Store settings, completa cada tienda. La API le entrega al kiosco solo la fila de su tienda.
- En cada kiosco, abre el dispositivo y la pestaña Payments. Los valores viven en
settings_overrides.payment_settings, con el id del pago como clave. Ver Configurar un dispositivo.
pinpad_type no está en el formulario. Si lo omites, el cliente usa ANDROID_USB. Para Bluetooth o detección automática, pon pinpad_type en ANDROID_BT o ANDROID_AUTO en los mismos ajustes del dispositivo con el endpoint Actualizar dispositivo de kiosco.
Un pago al que le falta un dato de la tienda o del dispositivo no llega al kiosco, así que su botón no aparece en el checkout. En el listado de dispositivos, la columna Payments muestra lo que sigue vacío.
Botón del checkout
Cada pago CliSiTef es un botón. El template del kiosco ya pinta una tarjeta por pago a partir deservices.payments.list. No agregas un componente de botón.
- Varias modalidades en un pago: el cliente elige una antes de que arranque el pinpad. El adaptador pregunta con
ui.select, títuloSelecione a forma de pagamentoy opcionesDébito,Crédito,VoucheryPix. Si cierra el selector, la promesa se rechaza y el pinpad no arranca. - Pix en su propio botón: crea un segundo pago con
modalities: ["PIX"]. Queda al lado de la tarjeta y del efectivo. El template trata como Pix un pago cuya única modalidad esPIX(isPixOnlyPaymenten los helpers del checkout) y muestra la ilustración de Pix. Cualquier otro pagoPIN_PADmuestra la ilustración de tarjeta.
Pix es una transferencia: el cliente paga con un QR desde su banco. El QR y el resultado igual pasan por los binarios nativos de CliSiTef (
@fire-spark/payments-clisitef-client), el mismo módulo que el débito y el crédito. Pix es una modalidad PIX de este pago. No puede funcionar por separado, ni como un método BANK_TRANSFER aparte.Usarlo en el SDK
Agrega los dos paquetes a la app del kiosco. No forman parte del template público. Fíjalos a la misma versión que@fire-spark/payments.
@fire-spark/payments-clisitef-client es el módulo Android y el config plugin de Expo. @fire-spark/payments-clisitef-pinpad-rn es el adaptador. Cobra con el adaptador: confirma, deshace y recupera una transacción después de un reinicio.
En app.config.ts:
binariesDir es absoluta, o relativa a la raíz de la app. Apúntala a una carpeta fuera de git:
.so, activa useLegacyPackaging (Android 14 y posteriores no cargan un libclisitef.so comprimido) y agrega los permisos de internet y Bluetooth. El prebuild se detiene con [clisitef] missing ... si falta el JAR o libclisitef.so.
Registra el adaptador una vez por pedido, con almacenamiento del dispositivo. Pasa storage siempre: una transacción que el débito dejó abierta sigue visible para el crédito, y la app puede deshacerla después de un reinicio. Software Express admite una sola instancia del cliente. El adaptador ya usa la compartida.
kioskConfig es lo que devuelve getKioskConfig. Los valores del dispositivo llegan en overrides.payment_settings.
El adaptador no dibuja nada. Los avisos llegan por setPaymentUI. Muestra el texto de CliSiTef tal como llega, en portugués.
Contrato del QR de Pix:
payload es el texto de copia y pega de Pix. Dibújalo como código QR. Un payload vacío lo oculta, y también lo oculta el fin de payIntent. expiresAt llega null: SiTef no manda vencimiento, y el plazo del cobro es de 180 segundos. Los mensajes siguen llegando debajo del QR. El control de cancelar rechaza la promesa del flujo.
Cobra el pago que eligió el cliente:
payIntent({ payment }) sigue colocando un tender. Para partir CliSiTef con otro método, llama a setTenders con una asignación y después a payIntent(). Ver Usar pagos en el SDK.
El plazo del cobro es de 180 segundos. Cubre la carga de tablas del pinpad, la elección de modalidad, la tarjeta y el PIN. Deja runtime.timeout_ms sin definir para conservar ese plazo. Un valor en el pago lo reemplaza, así que pon 180000 o más. Para subir el valor por defecto del adaptador, pasa timeoutMs:
order.getMissingPaymentFields(payment) lista los campos del dispositivo que siguen vacíos. La API ya oculta un pago incompleto. Usa el helper en la pantalla de administración del kiosco cuando quieras mostrar qué falta.
Qué ve el cliente
El mensaje del pinpad, el selector de modalidad cuando el pago tiene más de una, y el QR de Pix. EnPAID, imprime metadata.receipt.customer (texto plano, la vía del cliente) y sigue con el pedido. En FAILED con CANCELLED_BY_USER, vuelve a la lista de métodos sin mostrar un error. En AMBIGUOUS (metadata.needs_review), deja el cobro como está: la tarjeta puede haberse leído, o el QR puede haberse mostrado. Manda al cliente al mostrador.
El NSU, el código de autorización, la marca, los últimos 4 dígitos y el cupón fiscal están en result.metadata.payment. Pix no tiene marca ni últimos 4 (entry_mode: "QR"). El kiosco no los guarda por su cuenta.
Webhooks
Ninguno.Anulaciones
order.cancel() anula un pedido que no se entregó. order.refund() reembolsa uno que sí. Cada uno anula los cobros del pinpad y llama a su endpoint una vez.
El adaptador envía el monto, la fecha, el NSU del host y la clave de supervisor (
secret_supervisor_password del dispositivo o, si no hay, de la tienda). Si no hay ninguna, la pide con ui.input (type: "password"). Mantén setPaymentUI montado durante la anulación.
Errores comunes
Compatibilidad
Prompt para un agente
Pega esto en el agente que edita la app del kiosco. Cubre solo CliSiTef. Las secciones de arriba son el mismo trabajo, escrito para una persona.Prompt de integración