VibeFox Hubtel for WooCommerce — Ayuda

Requisitos

WordPress: 6.2 o posterior.

WooCommerce: 8.0 o posterior, instalado y activo. El plugin no se activará sin él.

PHP: 8.0 o posterior.

Moneda: únicamente cedi ghanés (GHS). El método de pago se oculta en la finalización de compra para otras monedas. Mantén el número de decimales de WooCommerce en 2, ya que Hubtel cobra pesewas enteros.

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 control de empresa de Hubtel en bo.hubtel.com en Programmable keys.

Lista blanca de IP: Hubtel responde a su Transaction Status API únicamente desde direcciones IP de servidores en lista blanca. Pide a Hubtel (a tu gestor de cuenta o a 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 los pedidos permanecen en Pendiente de pago.

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

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

Instalación

1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_hubtel_pay a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre la configuración: WooCommerce > Settings > Payments > Hubtel > Manage, o haz clic en Settings debajo del nombre del plugin en la página Plugins.

4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.

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

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

7. Activa Enable/Disable. La URL de callback se envía a Hubtel con cada pago, por lo que no hay que configurar nada en el panel de control de Hubtel.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Hubtel. Encima de los campos, la página te avisa cuando falta el API ID, el API Key o el número de cuenta de comerciante, y cuando la moneda de la tienda no es GHS. En ambos casos, Hubtel se oculta en la finalización de compra. También te avisa cuando la tienda usa más de 2 decimales. En la lista de métodos de pago, la pasarela aparece marcada como pendiente de configuración hasta que se introduzcan las credenciales.

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

Title: el nombre del método de pago que ve el cliente en la finalización de compra. Por defecto: Mobile Money or card (Hubtel).

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

Credenciales de API de Hubtel

Copia el API ID y el API Key de tu panel de control 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 inclusión de la IP en la lista blanca.

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

API Key (Client Secret): el API Key de tus claves programables de Hubtel. Mantenlo en privado.

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

Confirmación del pago

El callback informa a tu tienda de que se ha realizado un pago. La URL de callback que se muestra en esta sección se envía a Hubtel con cada pago, por lo que no es necesario configurar nada en el panel de control de Hubtel. Tiene el formato https://your-site/wc-api/hubtel_pay/. Debe ser accesible desde Internet: sin modo de mantenimiento, protección por contraseña o cortafuegos que bloquee a Hubtel.

Los callbacks de Hubtel no están firmados. El plugin toma del callback únicamente la referencia de pago; la referencia debe pertenecer a un pedido de tu tienda. El estado, el importe y el ID de transacción provienen siempre de la Transaction Status API de Hubtel. El pedido se marca como pagado solo después de que dicha API confirme el pago y su importe. Si no se puede contactar con Hubtel, el pago se vuelve a comprobar automáticamente en segundo plano, y puedes comprobarlo desde la pantalla del pedido con Order actions > Check Hubtel payment status.

Avanzado

Debug log: Log API calls and callbacks en WooCommerce > Status > Logs, origen wcp_hubtel_pay, sin claves ni datos de clientes. Los errores siempre se registran. Por defecto: desactivado.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept). Por defecto: desactivado.

Finalizar compra

El cliente elige el método de pago (por defecto Mobile Money or card (Hubtel)) y realiza el pedido. El plugin crea un checkout de Hubtel por el importe total del pedido en GHS y envía al cliente a la página de pago de Hubtel. El pago se muestra allí como Order #, el número de pedido y el nombre de tu sitio. En la página de Hubtel el cliente paga con MTN MoMo, Telecel Cash, AirtelTigo Money, una tarjeta Visa o Mastercard o GhQR. Cada clic en Place order o Pay crea un nuevo intento de pago con su propia referencia, y las páginas de Hubtel anteriores del mismo pedido siguen siendo pagaderas.

Tras pagar, el cliente regresa a la página de pedido recibido. El pedido se marca como pagado únicamente después de que Hubtel lo confirme a través de la Transaction Status API: mediante el callback, mediante la comprobación realizada cuando el cliente regresa, mediante una comprobación en segundo plano o mediante la acción del pedido. Si un callback y un retorno llegan al mismo tiempo, se procesan uno tras otro, por lo que el pedido nunca se completa dos veces. Si Hubtel aún no ha confirmado el pago, la página muestra 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. Si el pedido se puso en espera, muestra Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Si el cliente pulsa Cancel en la página de Hubtel, el plugin comprueba primero si el pago se realizó de todos modos. Si no es así, el cliente vuelve a la página Pay for order con el mensaje The Hubtel payment was cancelled. You can try again or choose another payment method.

Si Hubtel no puede iniciar el pago, el cliente ve 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étodo de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).

El plugin no permite reembolsos desde WooCommerce, no admite suscripciones, no guarda tarjetas y no permite elegir el canal de pago dentro de WooCommerce.

Pedidos

Estados del pedido

Pending payment: el cliente fue enviado a Hubtel y aún no ha pagado, o Hubtel aún no ha confirmado el pago.

Processing: el pago fue confirmado. Los pedidos que contienen únicamente productos virtuales descargables pasan a Completado, el valor predeterminado de WooCommerce. La nota del pedido muestra el importe, la transacción de Hubtel, el método de pago y la referencia. El ID de transacción es el ID de transacción de Hubtel.

On hold: Hubtel informó de un importe pagado que difiere del total del pedido, o el pedido no está en GHS (nota Hubtel amount/currency mismatch); o llegó un pago para un pedido que había sido cancelado. El pedido no se marcó como pagado. Comprueba el pago en el panel de control de Hubtel y completa o reembolsa el pedido manualmente.

Failed: Hubtel informó de que el último intento de pago de un pedido pendiente falló, y la Transaction Status API confirma que no está pagado. El cliente puede intentarlo de nuevo desde el pedido. Un fallo informado únicamente por un callback nunca hace fallar un pedido.

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

Comprobaciones del pago

Aproximadamente 20 minutos después de que el cliente sea enviado a Hubtel, una comprobación en segundo plano (WooCommerce Action Scheduler) consulta a Hubtel sobre el pago, en caso de que el callback se haya perdido y el cliente no haya regresado. Un intento no pagado se comprueba una vez más después de una hora. Cuando no se puede acceder a la API de Hubtel, la comprobación se repite hasta 5 veces con intervalos crecientes.

La acción del pedido Check Hubtel payment status comprueba los últimos intentos del pedido (hasta 5, el más reciente primero), aplica el resultado y añade una nota con el estado de cada intento.

Reembolsos

No se admiten reembolsos desde WooCommerce. Reembolsa el pago en el panel de control de Hubtel y luego crea un reembolso manual en WooCommerce.

Clave de licencia

El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Hubtel. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.

Una clave funciona en un dominio. Eliminar la clave de un sitio no libera su espacio de dominio. Libera el espacio 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. Los gestores de la tienda que hayan iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

Cuando caduca una licencia, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.

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, el API Key y el número de cuenta de comerciante estén completados y que la moneda sea GHS. En la página Pay for order cuenta la moneda del pedido. La página de ajustes muestra un aviso si las credenciales o la moneda son incorrectas.

El pago se realizó, pero el pedido sigue en Pendiente de pago: no se pudo confirmar el pago. Abre WooCommerce > Status > Logs, origen wcp_hubtel_pay. Un 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á en la lista blanca de Hubtel. Comprueba también que la URL de callback sea accesible desde Internet. Tras solucionarlo, abre el pedido y ejecuta Order actions > Check Hubtel payment status. Las comprobaciones en segundo plano también confirman el pedido una vez que Hubtel responde.

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

El callback responde Payment status unavailable: no se pudo acceder a la Transaction Status API o rechazó la solicitud. El pago se vuelve a comprobar en segundo plano.

El pedido está en espera con una nota de discrepancia de importe o moneda: Hubtel informó de un importe pagado que difiere del total del pedido, o el pedido no está en GHS. Comprueba el pago en el panel de control de Hubtel y completa o reembolsa el pedido manualmente.

El cliente ve un error al realizar el pedido: activa Debug log y consulta el registro. Unas claves de API incorrectas devuelven Hubtel payments are not available at the moment. Un problema de conexión devuelve Could not connect to Hubtel.

El bloque de licencia muestra un error: sigue las indicaciones del mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera un espacio en tu cuenta de vibefox.net y haz clic en Check now. Si la dirección del sitio ha cambiado, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.

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

Desinstalación

Al desactivar el plugin se conservan todos los datos; solo se cancelan las comprobaciones de pago pendientes en segundo plano. Para eliminarlo, desactívalo y elimínalo en la página Plugins. La clave de licencia y el estado de la licencia de este plugin siempre se eliminan. Los ajustes de la pasarela, las opciones propias del plugin, las comprobaciones pendientes en segundo plano y los registros se eliminan solo si Delete data on uninstall estaba activado. De lo contrario, se conservan para una posterior reinstalación. Los datos de Hubtel guardados en los pedidos son historial de pagos y siempre se conservan. Los pedidos existentes conservan sus notas de pago e ID de transacción.

Hubtel es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Hubtel ni cuenta con su respaldo.