SDK Web

El SDK Web de Cubo Pago es un conjunto de herramientas de desarrollo que permite a tu aplicación web interactuar directamente con los lectores de tarjetas de Cubo Pago a través de una conexión Bluetooth.

Con este SDK, tu plataforma puede iniciar y completar transacciones de pago de forma sencilla y segura. En la práctica, esto convierte cualquier navegador web compatible en un punto de venta totalmente funcional.

⚠️ Actualmente, este SDK funciona únicamente con el modelo de terminal Cubo QPOS Cute.

Requisitos previos

Antes de integrar el SDK, asegúrate de cumplir con los siguientes requisitos indispensables:

1. API Key generada en Cubo Admin
   Necesitas una API Key válida para poder realizar pagos. Si aún no la has generado, consulta nuestra guía.

2. Sitio en contexto seguro (HTTPS)
   Tu aplicación debe estar servida sobre https. Solo se permite http://localhost durante el desarrollo.

3. Bluetooth disponible y activado
   El dispositivo donde se ejecuta la app debe contar con conectividad Bluetooth.

4. Compatibilidad con navegadores
   El SDK funciona únicamente en los siguientes navegadores:

   • Chrome (Desktop y Android)
   • Edge (Desktop)
   • Opera (Desktop y Android)

Funcionalidades clave

Esta sección resume brevemente las funciones clave del SDK. Para ejemplos detallados de implementación, consulta el repositorio oficial.

🔗 Conexión con el lector

El SDK permite conectar y desconectar el lector de tarjetas mediante los métodos connect() y disconnect(). Estos métodos gestionan la conexión Bluetooth directamente desde el navegador.

💳 Iniciar pagos

Para procesar una transacción, se utiliza el método startPayment(), que recibe los siguientes parámetros:

• amount: Monto a cobrar en centavos (ej. "1250" para $12.50).
• currencyCode: Código numérico ISO 4217 (ej. "0840" para USD - "0320" para GTQ).
• currencySymbol: Símbolo de la moneda (ej. "$" - "Q").

📡 Escuchar eventos del SDK

El SDK emite varios eventos para informar sobre el estado del proceso de conexión y pago. Puedes escucharlos con el método on().

Eventos disponibles:

• connected: Se dispara cuando la conexión con el lector se establece correctamente.

• disconnected: Indica que el lector se ha desconectado (manualmente o por pérdida de señal).

• loading: Indica que hay una operación en curso (por ejemplo, procesando un pago).

• transactionResult: Devuelve el resultado final de una transacción.

• error: Se emite cuando ocurre un error en el SDK o en la comunicación con el lector.

• status: Informa sobre cambios en el estado general de conexión y pago. A continuación, se listan los estados posibles emitidos:

  Estado	Descripción
  searching	Buscando dispositivos Bluetooth
  connecting	Conectando con el dispositivo
  connected	Conexión establecida
  disconnected	Sin conexión
  waiting_for_card	Lector listo, esperando tarjeta
  processing_payment	Procesando información de la tarjeta
  payment_success	Transacción exitosa
  payment_failed	La transacción falló
  transaction_terminated	Informa que la transacción fue cancelada antes de completarse (por el usuario, por tiempo de espera, o por un error). No significa “Aprobada” ni “Declinada”.

Repositorio oficial

Visita el repositorio oficial para acceder a ejemplos completos, código y toda la documentación técnica. ¡Comienza tu integración hoy mismo! 🚀.

🔗 Cubo POS SDK Web Demo