En esta página
El plugin WooCommerce de Genius Checkout conecta una cuenta soportada de Mastercard Payment Gateway Services a una tienda en WordPress. Los comercios pueden usar MPGS Direct o Hosted Checkout siempre que el modo seleccionado, las credenciales y la moneda coincidan con la cuenta emitida por su banco o proveedor de pagos.
Esta guía refleja la integración revisada el 4 de septiembre de 2026.
| Requisito | Valor |
|---|---|
| Tienda | Instalación soportada de WordPress y WooCommerce |
| Gateway | MPGS Direct o MPGS Hosted Checkout |
| Credenciales | ID de comerciante, URL del gateway y autenticación específica del modo |
| Soporte de suscripciones | Requiere tokenización y permisos para pagos recurrentes |
| Liquidación | Controlada por el banco comerciante o el acuerdo de adquirencia |
Identifica el modo del gateway
MPGS Direct y Hosted Checkout requieren diferentes flujos de credenciales y navegación. Utiliza la URL del gateway y el ID de comerciante proporcionados para la cuenta. Crea u obtiene la autenticación API según las instrucciones del portal de comercios del banco.
Un comercio de Sagicor puede recibir acceso a MPGS, pero el nombre del banco por sí solo no determina cada campo de configuración. En las instrucciones, utiliza “tu banco, por ejemplo Sagicor” y asegúrate de coincidir con el paquete de onboarding recibido.
Configura MPGS en Genius Checkout
- Abre el comercio de Genius Checkout asignado a la tienda.
- Selecciona MPGS Direct o MPGS Hosted Checkout.
- Elige el modo de pruebas.
- Ingresa el ID de comerciante, la autenticación y la URL del gateway para el mismo entorno.
- Selecciona una moneda habilitada para la cuenta MPGS.
- Para Hosted Checkout, agrega el logotipo del comercio a través de la biblioteca de medios. Utiliza una imagen cuadrada de 1000 por 1000 píxeles como base.
- Guarda y resuelve cualquier mensaje de validación.
Conecta WooCommerce
- Instala el plugin Genius Checkout para WooCommerce actualizado.
- Abre la configuración de métodos de pago de Genius Checkout.
- Ingresa las credenciales API del comercio configurado.
- Autoriza el dominio de la tienda.
- Confirma el nombre del comercio y el modo de pruebas en el estado de conexión.
- Selecciona los métodos de pago disponibles para los compradores.
La lista permitida de dominios de la tienda protege la conexión API. No debería requerir verificación DNS para el uso de redirección del plugin.
Un comercio con múltiples gateways activos puede mostrar MPGS como una opción aparte para el comprador. Las opciones reales dependen de la configuración activa del comercio y de la moneda de la orden.
El plugin actual es compatible con WordPress 6.0 o superior, WooCommerce 8.0 o superior, PHP 8.0 o superior, WooCommerce High-Performance Order Storage, y tanto el checkout clásico como el Blocks. Consulta los requisitos vigentes en WordPress.org antes de modificar un sitio en producción.
Entiende la navegación de Hosted Checkout
MPGS Hosted Checkout opera en una página del proveedor. Dicha página puede bloquear la visualización dentro de un iframe. WooCommerce ya realiza una redirección a nivel superior, por lo que no necesita la pantalla intermedia de HighLevel.
El comprador debe poder cancelar, usar el botón Atrás del navegador y regresar a la tienda sin ser forzado a volver a MPGS. Una cancelación debe dejar la orden de WooCommerce disponible para reintento.
Ejecuta la matriz de pruebas
Prueba cada modo y entorno configurado de forma independiente:
- Pago único exitoso.
- Pago rechazado con un mensaje de error claro.
- Cancelación por parte del comprador.
- Uso del botón Atrás del navegador desde MPGS Hosted Checkout.
- Entrega duplicada de callback.
- Pago con tarjeta guardada cuando esté habilitado.
- Renovación de suscripción y reintento de renovación fallida cuando esté habilitado.
- Reembolso o anulación desde una orden WooCommerce.
Registra el ID de la orden, la transacción de Genius Checkout, el número del recibo, la referencia MPGS, la marca de tiempo UTC, el modo y el resultado. Nunca almacenes datos reales de tarjetas.
Pagos recurrentes
Un pago MPGS único puede aprobarse incluso si la cuenta del comercio no tiene habilitada la tokenización. WooCommerce Subscriptions requiere un token de pago reutilizable y un plan de Genius Checkout con capacidad para pagos recurrentes.
Para una prueba sin cargo inicial, verifica que WooCommerce pueda establecer el método de pago de la suscripción sin intentar cobrar un monto cero si no es compatible. Prueba la primera renovación de pago después de la prueba. Un reintento manual debe crear una nueva transacción en Genius Checkout.
Reembolsos y estado de pago
WooCommerce puede solicitar un reembolso desde la pantalla de la orden, pero la operación dependerá del estado de la transacción. Genius Checkout debe anular una autorización no capturada cuando MPGS lo permita, y reembolsar un pago capturado cuando MPGS lo permita.
La línea de tiempo de la transacción debe registrar el pago original y cada evento posterior de captura, anulación o reembolso.
Errores comunes de MPGS
HTTP 502 al iniciar. Verifica la respuesta ascendiente, el host del gateway, el modo, la moneda y las credenciales. Genius Checkout debe generar un registro de operación incluso si no existe una transacción financiera.
Fallo de autenticación. Asegúrate de que el ID de comerciante y la autenticación API correspondan a la URL y el entorno del gateway.
Hosted Checkout no abre. Asegúrate de que la cuenta tenga permisos para Hosted Checkout y que el navegador no intente mostrar la página del proveedor dentro de un iframe.
Renovación rechazada. Verifica la tokenización, permisos para pagos recurrentes, capacidad del plan, titularidad del token y el error API seguro retornado a WooCommerce.
Usa MPGS más allá de WooCommerce
Una configuración aprobada de comercio MPGS puede conectarse a través de Genius Checkout con HighLevel, Ecwid, GiveWP, enlaces de pago y códigos QR y otras integraciones API personalizadas compatibles. Prueba cada integración ya que la navegación, los callbacks y la gestión del estado de la orden varían según la plataforma de origen.
Fuentes y pasos siguientes
- Resumen de integración MPGS
- Resumen de integración WooCommerce
- Resumen de eCommerce Sagicor
- Documentación Genius Checkout WooCommerce
- Genius Checkout para WooCommerce en WordPress.org
- Documentación de la API Mastercard Gateway
Crea una cuenta en Genius Checkout o agenda una revisión de configuración.