VibeFox HyperPay for WooCommerce — Ayuda

Requisitos

WordPress: 6.0 o posterior.

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

PHP: 8.0 o posterior.

Cuenta de HyperPay: HyperPay emite el Access Token y el Entity ID cuando se configura tu cuenta de comerciante. Las credenciales de prueba y las reales son diferentes. También necesitas un webhook de pagos en el Panel de control de HyperPay y su clave de descifrado (webhook key), que aparece en Administration > Webhooks (consulta Configuración).

Datos de la tarjeta: la tarjeta se introduce solo en el widget de HyperPay, así que los datos de la tarjeta nunca llegan a tu servidor (PCI DSS SAQ A).

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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_hyperpay_payment_gateway a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre la configuración: WooCommerce > Settings > Payments > HyperPay > 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 Access Token, el Entity ID y la clave del webhook de prueba que te ha emitido HyperPay, y deja Test Mode activado.

6. En el Panel de control de HyperPay (Administration > Webhooks) añade un webhook de pagos con la URL que aparece en la configuración y copia su clave de descifrado en el campo de clave del webhook del mismo modo.

7. Activa Enable/Disable y haz un pago de prueba con una tarjeta de prueba de HyperPay. Después introduce las credenciales reales y desactiva Test Mode.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > HyperPay. Encima de los campos, la página muestra El modo de prueba está activado: los pagos van al sistema de pruebas de HyperPay y no se cobra dinero real. mientras el modo de prueba esté activado. Avisa cuando falta el Access Token o el Entity ID del modo actual (en ese caso, el método de pago no se muestra en la finalización de compra) y cuando el modo actual no tiene una clave de webhook válida (en ese caso, los pagos solo se confirman cuando el cliente vuelve a la tienda). En la lista de métodos de pago, la pasarela aparece marcada como pendiente de configuración hasta que el modo actual tenga su Access Token y su Entity ID. Al guardar, se eliminan los espacios de las credenciales, y la página muestra un error si una clave de webhook no es una clave hexadecimal de 64 caracteres.

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

Title: el título que ve el cliente durante la finalización de compra. Predeterminado: Credit/Debit Card (HyperPay).

Description: la descripción que ve el cliente durante la finalización de compra. Predeterminado: Pay securely using your credit or debit card.

Credenciales de API

El Access Token, el Entity ID y la clave del webhook los emite HyperPay cuando se configura tu cuenta de comerciante. Las credenciales de prueba y las reales son diferentes. La clave del webhook aparece en el Panel de control de HyperPay, en Administration > Webhooks.

Test Mode: Enable Test Mode usa el sistema de pruebas de HyperPay (eu-test.oppwa.com) y las credenciales de prueba. No se cobra dinero real. Desactívalo para aceptar pagos reales con las credenciales reales (eu-prod.oppwa.com). Predeterminado: activado.

Test Access Token: el token de portador de tu cuenta de pruebas de HyperPay.

Test Entity ID: el Entity ID del canal de pagos de pruebas.

Test Webhook Key: la clave hexadecimal de 64 caracteres que se usa para descifrar las notificaciones de webhook del sistema de pruebas.

Live Access Token: el token de portador de tu cuenta real de HyperPay.

Live Entity ID: el Entity ID del canal de pagos real.

Live Webhook Key: la clave hexadecimal de 64 caracteres que se usa para descifrar las notificaciones de webhook del sistema real.

Webhook

El webhook informa a tu tienda de los pagos incluso cuando el cliente cierra el navegador antes de volver a la tienda. En el Panel de control de HyperPay (Administration > Webhooks) añade un webhook para pagos con la URL que aparece en esta sección de la configuración. Tiene este formato: https://your-site/wp-json/hyperpay-p/v1/webhook. Después copia la clave de descifrado del webhook en Test Webhook Key o en Live Webhook Key, según el modo.

Los webhooks de HyperPay están cifrados (AES-256-GCM). Un webhook que no se puede descifrar con tus claves se rechaza. Solo se procesan las notificaciones de pago, y el pago debe pertenecer a una sesión de pago de uno de tus pedidos, creada en el mismo modo que la clave que lo descifró. Las notificaciones de prueba de HyperPay reciben acuse de recibo. El webhook también informa de las capturas, reversiones, reembolsos y contracargos realizados en el Panel de control de HyperPay (consulta Pedidos y reembolsos). Sin el webhook, un pago solo se confirma cuando el cliente vuelve a la tienda después de pagar.

Pago

Transaction Type: cómo se cobra la tarjeta.

Payment Brands: las marcas que se muestran en el widget de pago: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. Predeterminado: VISA y Mastercard. Selecciona solo las marcas que HyperPay haya activado para tu Entity ID; mada, STC Pay y Apple Pay suelen usar su propia entidad, que este plugin no admite.

Avanzado

Enable Logging: Log API requests and responses. La información de depuración se escribe en WooCommerce > Status > Logs, fuente wcp_hyperpay_payment_gateway. Los errores siempre se registran. Los registros no contienen datos de tarjeta, claves ni datos de clientes. Predeterminado: desactivado.

Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled. Elimina los ajustes y los archivos de registro al borrar el plugin. Los datos de HyperPay guardados en los pedidos se conservan. Predeterminado: desactivado.

Finalización de compra

El cliente elige el método de pago (por defecto Credit/Debit Card (HyperPay)) y hace clic en Continue to payment. Se crea el pedido y el cliente pasa a la página Pay for order. Allí, el plugin prepara una sesión de pago de HyperPay por el total del pedido en la moneda del pedido y muestra el widget de HyperPay con el mensaje Complete su pago a continuación:. El widget usa el idioma de tu sitio cuando HyperPay lo admite. En modo de prueba, la página muestra Modo de prueba: use una tarjeta de prueba de HyperPay; no se realizará ningún pago real. El cliente introduce los datos de la tarjeta en el widget.

Tras pagar, el cliente vuelve a tu tienda. El plugin comprueba que el pago pertenece a una de las sesiones de pago de este pedido y pide a HyperPay el resultado mediante una solicitud de servidor a servidor. El pedido se marca como pagado solo cuando HyperPay lo confirma: con esa solicitud o con el webhook. El importe y la moneda deben coincidir con los del pedido. Una vuelta y un webhook que llegan al mismo tiempo se procesan uno tras otro, de modo que el pedido nunca se procesa dos veces. Cuando el pago queda confirmado, el cliente llega a la página de pedido recibido.

Si el pago no se completó, el cliente vuelve a la página Pay for order con un mensaje: Pago fallido: y el motivo de HyperPay, El pago no se completó. Inténtalo de nuevo., o Todavía no hemos podido confirmar tu pago. Si se te ha cobrado, el pedido se actualizará automáticamente; si no, inténtalo de nuevo. El cliente puede volver a pagar en la misma página. Si no se puede preparar el widget, el cliente ve un mensaje breve, por ejemplo que el proveedor de pagos no aceptó algunos datos de facturación, y un botón Try Again. Los detalles se añaden a las notas del pedido.

Los importes se envían con dos decimales, como exige la API de HyperPay. En las monedas de 3 decimales (KWD, BHD, JOD, OMR), el total del pedido se redondea a dos decimales.

El método de pago funciona en la finalización de compra clásica, en los bloques de Carrito y Finalizar compra y en la página Pay for order. En modo de prueba, el bloque de Finalizar compra muestra Modo de prueba: no se realizará ningún pago real. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).

El plugin no admite reembolsos ni anulaciones desde WooCommerce, tarjetas guardadas ni tokenización, suscripciones, verificación de dominio de Apple Pay, una entidad separada por marca ni Tabby, Tamara u otros métodos de pago aplazado (buy now, pay later).

Pedidos y reembolsos

Estados del pedido

Pending payment: el cliente todavía no ha pagado, no terminó el widget o HyperPay aún no ha confirmado el pago.

Processing: se confirmó un pago con débito o se capturó una preautorización. Los pedidos con solo productos virtuales descargables pasan a Completado, el estado predeterminado de WooCommerce. La nota del pedido muestra el código de resultado de HyperPay, su descripción y el ID de pago. El ID de transacción es el ID de pago de HyperPay. Si HyperPay marcó el pago para revisión manual, la nota lo indica; revísalo en el Panel de control de HyperPay antes de enviar el pedido.

On hold (pre-authorization): el importe quedó reservado. Captúralo con la acción de pedido Capture HyperPay payment o desde el Panel de control de HyperPay; el webhook de captura completará entonces el pedido.

On hold after payment: HyperPay informó de un importe o una moneda distintos a los del pedido (por ejemplo, porque el pedido se editó después de abrir la página de pago), el pago sigue pendiente en HyperPay o el pago llegó después de que el pedido se hubiera cancelado. La nota del pedido lo explica. Revisa el pago en el Panel de control de HyperPay y complétalo o reembólsalo.

Failed: HyperPay rechazó el pago. El motivo está en la nota del pedido y se muestra al cliente. Un intento rechazado nunca cambia un pedido que ya está pagado, reservado, en espera o cancelado.

Cancelled: se revirtió una preautorización en el Panel de control de HyperPay, y el webhook de reversión cancela el pedido En espera.

Si llega otro pago correcto para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que reembolses el duplicado en el Panel de control de HyperPay. Un pago correcto para un pedido reembolsado solo añade una nota.

Captura

La acción de pedido Capture HyperPay payment aparece en los pedidos En espera con una preautorización que todavía no se ha capturado. Captura el total actual del pedido, menos los reembolsos ya registrados en WooCommerce, en el modo en el que se hizo la preautorización. Tras una captura correcta, el pedido pasa a Procesando. Si HyperPay rechaza la captura, se muestran el código de resultado y la descripción, y se añaden a las notas del pedido. La reversión (anulación) de una preautorización se hace en el Panel de control de HyperPay.

Reembolsos

No se admiten reembolsos desde WooCommerce. Reembolsa el pago en el Panel de control de HyperPay y regístralo en WooCommerce con Refund manually. Los reembolsos y contracargos realizados en HyperPay se añaden al pedido como nota mediante el webhook; el estado del pedido no cambia.

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 > HyperPay. 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 volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.

Una clave funciona en un solo dominio. Quitar la clave de un sitio no libera la plaza de su dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, HyperPay no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, el cliente ve Este método de pago no está disponible. Elige otro. Los gestores de la tienda que han iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedan configurar y probar el plugin antes de comprar una clave. Aparece un aviso 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 y las capturas funcionan.

Cuando una licencia caduca, 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

HyperPay no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga su Access Token y su Entity ID: los de prueba en modo de prueba, y los reales en modo real. La página de configuración muestra un aviso cuando faltan.

El pago se realizó, pero el pedido sigue como Pending payment: el webhook no funciona y el cliente no volvió a la tienda. En el Panel de control de HyperPay, comprueba que el webhook de pagos existe para el modo que usas, que su URL es exactamente la que aparece en la configuración y que su clave de descifrado está en el campo de clave del webhook del mismo modo. Revisa WooCommerce > Status > Logs, fuente wcp_hyperpay_payment_gateway.

El webhook responde Decryption failed: la clave del webhook pertenece a otro webhook u otro modo. Copia la clave de nuevo desde el Panel de control de HyperPay.

El webhook responde Webhook key not configured: no hay ninguna clave de webhook válida configurada. Pega la clave de 64 caracteres en los ajustes. HyperPay reintenta el webhook.

El registro muestra Webhook ignored: el pago no pertenece a un pedido de esta tienda o se hizo en el otro modo. Los pagos de prueba y los reales se mantienen separados.

El formulario de pago no se carga: lee la nota del pedido. Un error de configuración suele significar un Access Token o un Entity ID incorrectos para el modo actual. Un mensaje sobre datos de facturación significa que HyperPay no aceptó algunos datos del cliente. Asegúrate de que las Payment Brands seleccionadas estén activadas para tu Entity ID.

El pedido está On hold con una nota de discrepancia de importe o moneda: HyperPay informó de un pago que no coincide con el total o la moneda del pedido, por ejemplo porque el pedido se editó después de abrir la página de pago. Revisa el pago en el Panel de control de HyperPay y complétalo o reembólsalo.

La captura falla: lee el código de resultado y la descripción en la nota del pedido. La captura se envía en el modo de la preautorización, así que las credenciales de ese modo deben estar configuradas.

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

Para desarrolladores: el filtro hyperpay_p_icon cambia el icono del método de pago.

Desinstalación

Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes de la pasarela, los datos temporales del plugin y los archivos de registro solo se eliminan si Delete Data on Uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los datos de HyperPay guardados en los pedidos siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

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