Guía completa para configurar terminales de pago (datáfonos) con VERTEX POS. Soportamos los proveedores más utilizados en Guatemala.

Proveedores Compatibles

Proveedor Tipo Conexión Tarjetas Aceptadas
Paggo Terminal física + QR + Link API REST (Internet) Visa, Mastercard
Recurrente POS Pro Terminal inteligente API REST (Internet) Visa, Mastercard, Amex
Neonet (VisaNet) Terminal física Ingenico TCP/IP (Red local) Visa, Mastercard
BAC Credomatic Terminal física Manual (voucher) Visa, Mastercard, Amex

1. Paggo

¿Qué es Paggo?

Paggo es una pasarela de pagos guatemalteca que permite aceptar tarjetas de crédito y débito mediante terminales físicas, códigos QR y links de pago. Es ideal para negocios que requieren múltiples métodos de cobro digital.

Configuración

  1. Cree una cuenta en paggoapp.com
  2. Obtenga sus credenciales API (Public Key y Secret Key)
  3. En VERTEX, vaya a Configuración POS → Pagos → Datáfonos
  4. Seleccione Paggo como proveedor
  5. Ingrese sus credenciales:
  • API Key pública
  • API Key secreta
  • Webhook Secret (opcional, recomendado para producción)
  1. Seleccione el ambiente (Sandbox para pruebas o Producción)

Métodos de Pago Disponibles

Método Descripción
Terminal física Envía el monto al datáfono Paggo para que el cliente pase su tarjeta
Código QR Genera un QR que el cliente escanea con su app bancaria o Paggo
Link de pago Genera un enlace para pagar desde el celular del cliente

Flujo de Cobro con Terminal Paggo

  1. En el POS, complete la venta y seleccione Tarjeta como método de pago
  2. El sistema enviará automáticamente el monto al datáfono Paggo
  3. El cliente presenta su tarjeta (chip, contactless o banda magnética)
  4. El datáfono procesa el pago y devuelve la autorización
  5. VERTEX registra la transacción con el código de autorización

Cuotas

Paggo permite cobros en cuotas (3, 6 y 12 meses) según lo soporte la tarjeta del cliente. Esta opción aparecerá automáticamente en el modal de pago si está habilitada en su cuenta Paggo.

2. Recurrente POS Pro

¿Qué es Recurrente?

Recurrente es la pasarela de pagos más utilizada en Guatemala. Su terminal POS Pro es un datáfono inteligente con pantalla táctil que permite cobrar tarjetas, generar QR y enviar links de pago.

Configuración

  1. Solicite su POS Pro en recurrente.com
  2. Obtenga sus credenciales de API (Public Key y Secret Key)
  3. En VERTEX, vaya a Configuración POS → Pagos → Datáfonos
  4. Seleccione Recurrente como proveedor
  5. Ingrese sus credenciales:
  • Llave pública (pk_live_...)
  • Llave secreta (sk_live_...)
  1. Configure su Store ID y POS Pro ID (formato: store_id:pos_pro_id)
  • Puede encontrar estos IDs en su panel de Recurrente → Tiendas → POS Pro

Flujo de Cobro con POS Pro

  1. En el POS, seleccione Tarjeta al momento de cobrar
  2. VERTEX crea automáticamente una venta en el POS Pro (API: /stores/{id}/pos_pros/{id}/sales)
  3. La pantalla del POS Pro mostrará el monto a cobrar
  4. El cliente presenta su tarjeta en el POS Pro
  5. Recurrente procesa el pago y notifica a VERTEX
  6. La venta se completa automáticamente con el código de autorización

Cuotas con Recurrente

Recurrente soporta cuotas de 1, 3, 6 y 12 meses. Al crear la venta en el POS Pro, VERTEX envía el número de cuotas seleccionado.

Webhooks

Para recibir notificaciones automáticas de pagos:

  1. En su panel de Recurrente, vaya a Configuración → Webhooks
  2. Configure la URL: https://su-dominio.com/api/recurrente/webhooks
  3. Seleccione los eventos: checkout.completed, checkout.expired, pos_pro.sale.paid

3. Neonet (VisaNet Guatemala)

¿Qué es Neonet?

Neonet es el procesador de pagos de VisaNet Guatemala. VERTEX se comunica directamente con la terminal Ingenico (Desk/3500) a través de la red local usando el protocolo ZVT, sin necesidad de software intermediario.

Requisitos

  • Terminal Ingenico Desk/3500 CL / Eth con modo ECR habilitado
  • La terminal debe estar conectada a la misma red que el servidor VERTEX
  • Puerto TCP abierto (por defecto: 20007)
  • Protocolo configurado como ZVT (solicitarlo a Neonet)

Configuración

  1. Solicite a Neonet la activación del modo ECR en su terminal
  2. Conecte la terminal a la red por cable Ethernet
  3. Anote la dirección IP asignada a la terminal (ej: 192.168.68.102)
  4. En VERTEX, vaya a Configuración POS → Pagos → Datáfonos
  5. Seleccione Neonet como proveedor
  6. Configure:
  • IP del terminal: 192.168.68.102
  • Puerto: 20007
  • Protocolo: ZVT
  • Password: 000000 (predeterminado)
  • Moneda: GTQ (código 320)

Flujo de Cobro con Terminal Neonet

  1. En el POS, seleccione Tarjeta al momento de cobrar
  2. VERTEX envía el comando ZVT de autorización directamente a la terminal
  3. La terminal muestra "Presente su tarjeta" al cliente
  4. El cliente inserta/acerca su tarjeta y digita su PIN si aplica
  5. La terminal procesa con VisaNet y devuelve la autorización
  6. VERTEX recibe: código de autorización, últimos 4 dígitos, marca de tarjeta

Verificación de Conexión

Para verificar que la terminal está correctamente configurada:

  1. Vaya a Configuración POS → Pagos → Datáfonos
  2. Haga clic en "Probar conexión"
  3. El sistema intentará conectarse a la IP y puerto configurados
  4. Si la conexión es exitosa, verá un mensaje verde de confirmación

Solución de Problemas Neonet

Error Causa Solución
Terminal rechazó la conexión Modo ECR no activado Contacte a Neonet para activar ECR
Terminal inalcanzable Terminal en otra red o apagada Verifique la conexión Ethernet
Tiempo de conexión agotado Firewall bloqueando el puerto Abra el puerto 20007 en el router
Terminal finalizó sin resultado Error en la comunicación ZVT Reinicie la terminal y reintente

4. BAC Credomatic

¿Qué es BAC?

BAC Credomatic es uno de los bancos más grandes de Centroamérica. Su terminal de pagos es ampliamente utilizada en Guatemala. Actualmente, la integración con BAC en VERTEX es semi-automática: el monto se envía al datáfono, pero el código de autorización se ingresa manualmente.

Configuración

  1. Solicite su terminal BAC a su ejecutivo de cuenta
  2. En VERTEX, vaya a Configuración POS → Pagos → Datáfonos
  3. Seleccione BAC como proveedor
  4. No se requieren credenciales API (operación manual)

Flujo de Cobro con Terminal BAC

  1. En el POS, seleccione Tarjeta al momento de cobrar
  2. En la terminal BAC, ingrese el monto manualmente
  3. El cliente presenta su tarjeta
  4. La terminal procesa el pago
  5. Ingrese en VERTEX:
  • Código de autorización (6 dígitos del voucher)
  • Últimos 4 dígitos de la tarjeta (opcional)
  1. VERTEX registra la venta con la referencia BAC

Comparativa de Proveedores

Característica Paggo Recurrente Neonet BAC
Integración automática ✅ ✅ ✅ ⚠️ Semi-manual
QR Code ✅ ✅ ❌ ❌
Link de pago ✅ ✅ ❌ ❌
Cuotas ✅ 3/6/12 ✅ 1/3/6/12 ❌ ✅ Según banco
Reembolsos ✅ API ✅ API ⚠️ Pendiente ❌ Manual
Requiere internet ✅ ✅ ❌ Red local N/A
Webhooks ✅ ✅ ❌ ❌

Configuración General

Múltiples Proveedores

VERTEX permite configurar múltiples proveedores de pago simultáneamente. Por ejemplo, puede tener Paggo para QR y Neonet para tarjetas físicas. El sistema mostrará todas las opciones disponibles al momento de cobrar.

Reporte de Pagos con Tarjeta

Todos los pagos con tarjeta se agrupan como "Tarjeta" en los reportes de Corte de Caja (Corte X y Corte Z), independientemente del proveedor utilizado. Esto facilita la conciliación con los estados de cuenta bancarios.

Preguntas Frecuentes

¿Puedo usar VERTEX POS sin datáfono?

Sí. El datáfono es opcional. Puede recibir pagos solo en efectivo y tarjetas de regalo.

¿Qué pasa si el datáfono no procesa el pago?

El POS mostrará un mensaje de error con la causa (tarjeta rechazada, sin conexión, etc.). Puede reintentar o cambiar a otro método de pago.

¿Los pagos con tarjeta se reflejan en el Corte Z?

Sí. Todos los pagos con tarjeta se suman automáticamente en el Corte Z bajo la columna "Tarjeta", con el desglose por transacción disponible.

¿Puedo usar Paggo y Recurrente al mismo tiempo?

Sí. Puede configurar ambos y elegir cuál usar al momento de cada cobro.

Configuración: /apps/pos/config/general → Sección Pagos

Composable de referencia: composables/useTerminalPayment.ts

Adaptadores: server/services/payments/adapters/