VibeFox Hubtel for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior con la extensión cURL. El módulo no se instala sin ellos.

Moneda: solo cedi ghanés (GHS). El método de pago se oculta en la finalización de compra para las demás monedas. Mantén en 2 el número de decimales de la moneda GHS, porque Hubtel cobra en pesewas completos.

Cuenta de Hubtel: una cuenta de empresa de Hubtel con claves de API (API ID y API Key) y el número de cuenta de comerciante (POS Sales ID). Las claves están en el panel de empresa de Hubtel en bo.hubtel.com, en Programmable keys.

Lista blanca de IP: Hubtel responde a su Transaction Status API solo desde direcciones IP de servidor incluidas en la lista blanca. Pide a Hubtel (tu gestor de cuenta o support@hubtel.com) que incluya en la lista blanca la dirección IP pública de tu servidor web. Hasta entonces los pagos no se pueden confirmar y no se crea ningún pedido.

Sin entorno de pruebas: Hubtel no tiene un sandbox público. Todos los pagos son reales.

Cron: se recomienda una tarea cron del servidor que llame a la URL cron del módulo cada 5 minutos para las comprobaciones de pago en segundo plano (ver Configuración).

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.

Instalación

1. En el back office ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.

2. Cuando termine la subida, haz clic en Configure, o busca más tarde VibeFox Hubtel Pay Gateway en la lista de módulos y haz clic en Configure.

3. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (ver Clave de licencia).

4. Introduce el API ID, la API Key y el número de cuenta de comerciante (POS Sales ID).

5. Pide al soporte de Hubtel que incluya en la lista blanca la IP de tu servidor para la Transaction Status API.

6. Añade la URL cron que aparece en la página Configure al cron de tu servidor.

7. Activa Enable/Disable y haz clic en Save. La URL de callback se envía a Hubtel con cada pago, así que no hay que configurar nada en el panel de Hubtel.

Al instalarse, el módulo crea el estado de pedido Hubtel payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa si faltan el API ID, la API Key o el número de cuenta de comerciante, y si la moneda predeterminada de la tienda no es GHS. En ambos casos Hubtel se oculta en la finalización de compra. También avisa si la moneda GHS usa más de 2 decimales.

Hubtel

Enable/Disable: Enable Hubtel payments activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que ve el cliente en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Mobile Money or card (Hubtel). Obligatorio: un título vacío da el error Enter a title for the payment method.

Description: el texto que aparece bajo el método de pago en la finalización de compra. Predeterminado: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. Serás redirigido a Hubtel para completar el pago.

Credenciales de la API de Hubtel

Copia el API ID y la API Key desde tu panel de empresa de Hubtel: bo.hubtel.com > Programmable keys. El número de cuenta de comerciante es el POS Sales ID de tu cuenta de Hubtel. La sección también repite el aviso sobre la lista blanca de IP.

API ID (Client ID): el API ID de tus claves programables de Hubtel.

API Key (Client Secret): la API Key de tus claves programables de Hubtel. Mantenla en privado. La clave guardada nunca se vuelve a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla.

Merchant account number (POS Sales ID): los pagos se cobran en esta cuenta de Hubtel y se verifican contra ella.

Clear saved API Key: marca la casilla y haz clic en Save para eliminar la API Key guardada. Un campo vacío mantiene el valor guardado.

Confirmación del pago

Callback URL: el callback avisa a tu tienda de que se ha realizado un pago. Esta URL se envía a Hubtel con cada pago, así que no hay que configurar nada en el panel de Hubtel. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_hubtel_pay/callback, posiblemente con un código de idioma. Debe ser accesible desde internet: sin protección con contraseña ni cortafuegos que bloquee a Hubtel. El callback también funciona mientras la tienda está en modo mantenimiento y no está bloqueado por la restricción de países de tu tienda.

Los callbacks de Hubtel no están firmados. El módulo toma del callback solo la referencia del pago; la referencia debe pertenecer a un pago de tu tienda. El estado, el importe y el ID de transacción siempre vienen de la Transaction Status API de Hubtel. El pedido se crea como pagado solo después de que esa API confirme el pago y su importe.

Comprobaciones de pago en segundo plano (cron): la URL cron con un token secreto. Llámala cada 5 minutos desde el cron de tu servidor, por ejemplo con curl. Los pagos sin confirmar se vuelven a comprobar automáticamente con Hubtel: 20 minutos después de que el cliente fuera enviado a Hubtel, otra vez tras una hora si el pago sigue sin pagar, y hasta 5 veces con intervalos crecientes cuando no se pudo contactar con Hubtel. Mantén la URL en privado.

Avanzado

Debug log: registra las llamadas a la API y los callbacks en logs/hubtel_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves y los datos de clientes no se registran. Los errores y las advertencias siempre se registran, aunque esta opción esté desactivada. Predeterminado: desactivado.

Log: muestra el tamaño actual y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Delete data on uninstall: si está activada, al desinstalar el módulo se eliminan sus ajustes y su registro. Los datos de Hubtel guardados en los pedidos y el estado de pedido Hubtel payment on hold siempre se conservan. Predeterminado: desactivado.

Finalización de compra

En el paso de pago el cliente elige el método de pago (por defecto Mobile Money or card (Hubtel)) y confirma. El módulo crea una finalización de compra de Hubtel por el total del carrito en GHS y envía al cliente a la página de pago de Hubtel. El pago aparece allí como Cart #, el número de carrito y el nombre de tu tienda. En la página de Hubtel el cliente paga con MTN MoMo, Telecel Cash, AirtelTigo Money, una tarjeta Visa o Mastercard o GhQR. En este punto todavía no existe ningún pedido. Cada confirmación en el paso de pago crea un nuevo intento de pago con su propia referencia, y las páginas de Hubtel anteriores del mismo carrito siguen permitiendo pagar.

Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Hubtel lo confirma mediante la Transaction Status API: por el callback, por la comprobación que se hace cuando el cliente regresa, por una comprobación en segundo plano o con el botón de la página del pedido. Un callback y un regreso que llegan al mismo tiempo se procesan uno tras otro, así que el pedido nunca se crea dos veces. Después el cliente ve la página estándar de confirmación del pedido. Si el pedido se puso en espera, la página muestra Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Si Hubtel todavía no ha confirmado el pago cuando el cliente vuelve, se muestra una página Payment confirmation con el texto We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. y los botones Check again y Back to checkout. El pedido se crea en cuanto Hubtel confirma el pago. Si Hubtel ya ha registrado este intento de pago como fallido, el cliente vuelve a la finalización de compra con The Hubtel payment was not completed. You can try again or choose another payment method. El carrito se conserva.

Si el cliente pulsa Cancel en la página de Hubtel, el módulo primero comprueba si el pago se realizó de todos modos. Si no, el cliente vuelve a la finalización de compra con The Hubtel payment was cancelled. You can try again or choose another payment method. El carrito se conserva. Un pago posterior desde la página de Hubtel cancelada sigue siendo aceptado.

Si Hubtel no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo Could not connect to Hubtel. Please try again in a moment., Hubtel could not start the payment. Please try again or choose another payment method. o, con credenciales incorrectas, Hubtel payments are not available at the moment. Please choose another payment method. Los detalles van al registro.

El módulo no permite reembolsos desde PrestaShop, no admite suscripciones, no guarda tarjetas y no permite elegir el canal de pago dentro de la tienda.

Pedidos

Estados de pedido

No order yet: el cliente fue enviado a Hubtel y no ha pagado, o Hubtel todavía no ha confirmado el pago. Solo existe el carrito.

Payment accepted: el pago fue confirmado por el total exacto del carrito en GHS. El pago se registra con el ID de transacción de Hubtel, y una nota muestra el importe, la transacción de Hubtel, el método de pago y la referencia.

Hubtel payment on hold: Hubtel informó de un importe pagado distinto del total del carrito, o el carrito no está en GHS. El pedido no se marcó como pagado; el importe que Hubtel realmente cobró se registra como pago y una nota explica la diferencia. Revisa el pago en el panel de Hubtel y procesa el pedido o reembólalo manualmente. Si un intento posterior del mismo carrito se paga por el importe correcto, el pedido pasa a Payment accepted.

Si un intento de un pedido que ya está pagado también se paga, el pedido no cambia. Una nota pide que reembolses el duplicado en tu panel de Hubtel. Un pago de un pedido cancelado o reembolsado añade una nota, y el pedido nunca se reabre automáticamente. Cuando Hubtel informa de que un pago está reembolsado, se añade una nota al pedido.

Bloque de pago de Hubtel

La página del pedido muestra un bloque Hubtel payment con todos los intentos de pago del carrito del pedido: fecha, referencia, página de pago de Hubtel, importe, estado en Hubtel, transacción y resultado. Debajo de los intentos enumera las Hubtel notes del pedido, de la más reciente a la más antigua.

El botón Check Hubtel payment status comprueba los intentos más recientes del pedido (hasta 5, del más reciente al más antiguo, deteniéndose cuando el pedido ya está pagado), aplica el resultado y añade una nota con el estado de cada intento. El resultado se muestra en el bloque. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. El botón está disponible cuando el pedido existe. Un carrito pagado sin pedido se confirma mediante el callback, el regreso del cliente o el cron.

Reembolsos

Los reembolsos desde PrestaShop no son compatibles. Reembolsa el pago en el panel de Hubtel y después registra el reembolso en PrestaShop. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Hubtel.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Hubtel Pay Gateway es el primer bloque de Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure, por encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-hubtel y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen inglés y ruso).

Si la clave no se acepta, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de cambiar la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Eliminar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Hubtel no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el método de pago también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose también mediante las comprobaciones de pago en segundo plano.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez por semana. Para la comprobación de la licencia no se necesita ninguna tarea cron. Al desinstalar o restablecer el módulo, siempre se elimina la clave de licencia y el estado de la licencia.

Solución de problemas

Hubtel no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el API ID, la API Key y el número de cuenta de comerciante están rellenados y que la moneda del carrito es GHS. En Payment > Preferences comprueba que el módulo está permitido para GHS, el país del cliente y el grupo del cliente. La página de ajustes muestra un aviso cuando las credenciales o la moneda son incorrectas.

El pago se realizó, pero no se creó ningún pedido: el pago no pudo confirmarse. Activa Debug log y revisa el campo Log en la página del módulo. HTTP 401 o 403 en la comprobación de estado significa que las claves de API son incorrectas o que la IP del servidor no está incluida en la lista blanca de Hubtel. Comprueba también que la URL de callback es accesible desde internet y que se llama a la URL cron. En cuanto Hubtel responda, el siguiente callback, la siguiente comprobación en segundo plano o el siguiente regreso del cliente creará el pedido.

El callback responde Unknown reference: la referencia del pago no pertenece a un pago de esta tienda.

El callback responde Payment status unavailable: no se pudo contactar con la Transaction Status API o rechazó la solicitud, o el carrito estaba siendo confirmado por otra solicitud en ese mismo momento. El pago se vuelve a comprobar en segundo plano después de 5 minutos.

El callback responde Gateway not configured: falta el API ID, la API Key o el número de cuenta de comerciante. Complétalos; el pago se vuelve a comprobar en segundo plano.

El callback responde Invalid request o Invalid ClientReference: la solicitud no contenía un callback válido de Hubtel.

La URL de callback muestra Method not allowed en el navegador: es normal. La URL solo acepta solicitudes de Hubtel.

La URL cron responde Forbidden: el token de la URL es incorrecto. Copia la URL cron exactamente como aparece en los ajustes.

El pedido es Hubtel payment on hold: lee las notas del bloque Hubtel payment (ver Estados de pedido), revisa el pago en el panel de Hubtel y procesa el pedido o reembólalo manualmente.

El cliente ve un error al elegir Hubtel: activa Debug log y revisa el registro. Las claves de API incorrectas dan Hubtel payments are not available at the moment. Un problema de conexión da Could not connect to Hubtel. Un carrito en otra moneda da Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method.

Para desarrolladores: el hook actionWcpHubtelPayIcon cambia el icono del método de pago, y actionWcpHubtelPayPaymentDescription cambia la descripción del pago en la página de Hubtel (hasta 100 caracteres).

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Hubtel Pay Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes y el registro de este módulo. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los datos de Hubtel guardados para los pedidos y el estado de pedido Hubtel payment on hold siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Hubtel es una marca comercial de su titular. Este módulo no está afiliado a Hubtel ni cuenta con su respaldo.