VibeFox HyperPay for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior con la extensión OpenSSL (descifra los webhooks). Sin ella, el módulo no se puede instalar.

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 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 carga, haz clic en Configure, o busca más tarde VibeFox HyperPay Payment Gateway en la lista de módulos y haz clic en Configure.

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

4. Introduce el Access Token, el Entity ID y la clave de webhook de prueba que te emitió HyperPay, y deja activado Test Mode.

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

6. Activa Enable/Disable, haz clic en Save y realiza un pago de prueba con una tarjeta de prueba de HyperPay. Después, introduce las credenciales reales y desactiva Test Mode.

Al instalarse, el módulo crea tres estados de pedido: Awaiting HyperPay payment, HyperPay payment authorized y HyperPay payment on hold. PrestaShop vincula un nuevo módulo de pago a las monedas, los países y los grupos de clientes que estén activos en ese momento. Los países que actives más tarde deben permitirse en Payment > Preferences.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra Test mode is on: payments go to the HyperPay test system and no real money is charged. mientras el modo de prueba esté activado. Avisa si 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 si 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). Al guardar, se eliminan los espacios de las credenciales, y la página avisa si una clave de webhook no es una clave hexadecimal de 64 caracteres.

HyperPay

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

Title: el título que ve el cliente durante la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Por defecto: Credit/Debit Card (HyperPay). Obligatorio.

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

Credenciales de API

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

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). Por defecto: activado. Mientras esté activado, los clientes ven Test mode: no real payment will be made. debajo del método de pago.

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

Test Entity ID: el Entity ID del canal de pago de prueba.

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 pago real.

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

Los access tokens y las claves de webhook guardados nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.

Borrar credenciales guardadas: marca un token o una clave y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.

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 Webhook URL en esta sección. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_hyperpay_payment_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como la muestran los ajustes. Después, copia la clave de descifrado del webhook en Test Webhook Key o en Live Webhook Key, según corresponda al mismo modo.

Los webhooks de HyperPay están cifrados (AES-256-GCM). Un webhook que no se pueda 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 carritos, creada en el mismo modo que la clave que lo descifró. Las notificaciones de prueba de HyperPay se confirman. El webhook también informa de las capturas, reversiones, reembolsos y contracargos hechos en el panel de control de HyperPay (ver Pedidos y reembolsos). Sin el webhook, un pago solo se confirma cuando el cliente vuelve a la tienda tras pagar.

Payment

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. Por defecto: VISA y Mastercard. Si no se marca ninguna marca, la página avisa y el widget muestra 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 módulo no admite.

Advanced

Enable Logging: registra las solicitudes y respuestas de la API en logs/hyperpay_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran. Los registros no contienen datos de tarjeta, claves ni datos de clientes. Por defecto: desactivado.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Delete Data on Uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes, la tabla de intentos de pago de HyperPay y los archivos de registro. Los pedidos y los estados de pedido del módulo se conservan. Por defecto: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto, Credit/Debit Card (HyperPay)) y confirma el pedido. El módulo prepara una sesión de pago de HyperPay por el total del carrito en la moneda del carrito y abre la página HyperPay payment de tu tienda con el widget de HyperPay y Please complete your payment below:. El widget usa el idioma del cliente cuando HyperPay lo admite. En modo de prueba, la página muestra Test mode: use a HyperPay test card, no real payment will be made. El cliente introduce los datos de la tarjeta en el widget, o sigue Choose another payment method para volver a la finalización de compra. En este punto todavía no existe ningún pedido. Si se recarga la página, se reutiliza la misma sesión de pago durante hasta 25 minutos, siempre que el carrito no cambie.

Después de pagar, el cliente vuelve a tu tienda. El módulo comprueba que el pago pertenece a una sesión de pago de este carrito y pide a HyperPay el resultado mediante una solicitud de servidor a servidor, en el modo en el que se creó la sesión. 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 carrito. Si el retorno y un webhook llegan al mismo tiempo, se procesan uno tras otro, de modo que el pedido nunca se crea dos veces. Cuando el pago se confirma, se crea el pedido y el cliente ve la página estándar de confirmación del pedido.

Si el pago no se completó, el cliente vuelve a la finalización de compra con un mensaje: Payment failed: y el motivo de HyperPay, Payment was not completed. Please try again., o We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. El carrito se conserva y el cliente puede volver a pagar; cada nuevo intento recibe una nueva sesión de pago de HyperPay. Si no se puede preparar el formulario de pago, el cliente se queda en la finalización de compra con un mensaje breve, por ejemplo que el proveedor de pagos no ha aceptado algunos datos de facturación, o que el formulario de pago no está disponible por un error de configuración del pago. El motivo técnico se escribe en el registro.

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 carrito se redondea a dos decimales.

El webhook funciona aunque la tienda esté en modo de mantenimiento y no se ve afectado por la restricción de países de tu tienda.

El módulo no admite reembolsos ni anulaciones desde PrestaShop, ni tarjetas guardadas o tokenización, ni suscripciones, ni verificación de dominio de Apple Pay, ni una entidad separada por marca, ni Tabby, Tamara u otros métodos de pago aplazado (compra ahora, paga después).

Pedidos y reembolsos

Estados de pedido

No order yet: el cliente fue enviado a la página de pago y no ha pagado, el pago fue rechazado o HyperPay todavía no ha confirmado el pago. Solo existe el carrito.

Payment accepted: se confirmó un pago con débito o se capturó una preautorización. El pago se registra con el ID de pago de HyperPay como ID de transacción, y una nota privada muestra el código de resultado de HyperPay, su descripción y el ID de pago. 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.

HyperPay payment authorized: el importe quedó reservado mediante una preautorización. Captúralo en el bloque de HyperPay del pedido o en el panel de control de HyperPay; el webhook de captura entonces cambia el pedido a Payment accepted.

Awaiting HyperPay payment: HyperPay informó de que el pago está pendiente. El pedido pasa a Payment accepted cuando HyperPay lo confirma.

HyperPay payment on hold: HyperPay informó de un importe o una moneda distintos de los del carrito o del pedido (por ejemplo, el carrito se cambió después de abrir la página de pago), o el pago llegó después de que el pedido se cancelara. La nota lo explica. Revisa el pago en el panel de control de HyperPay y, después, prepara el pedido o reembolsa el pago.

Canceled: una preautorización se revirtió en el panel de control de HyperPay, y el webhook de reversión cancela el pedido autorizado.

Un resultado de rechazo (declined) nunca cambia un pedido existente. Si llega otro pago correcto para un pedido que ya está pagado, el pedido no cambia. Una nota te pide reembolsar el duplicado en el panel de control de HyperPay. Un pago correcto para un pedido reembolsado solo añade una nota.

Bloque de pago de HyperPay

La página del pedido muestra un bloque HyperPay payment con el ID de pago (y el ID de captura después de una captura), el tipo de transacción, el ID de la sesión de pago, el ID de transacción del comerciante, el importe enviado a HyperPay, el resultado y un distintivo Test mode para los pagos de prueba. Las notas del módulo están en los mensajes privados del pedido.

Captura

Para un pedido en HyperPay payment authorized, el bloque muestra Capture payment con el importe. Haz clic y confirma Capture the pre-authorized amount through HyperPay?. Se captura el total actual del pedido, en el modo en el que se hizo la preautorización, por lo que deben estar configurados el Access Token y el Entity ID de ese modo. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas del módulo. Tras una captura correcta, el pedido pasa a Payment accepted y el ID de captura se añade al pago y a las notas. Si HyperPay rechaza la captura, se muestran el código de resultado y la descripción, se añaden a las notas y el pedido sigue autorizado. Un doble clic no captura dos veces. La reversión (anulación) de una preautorización se hace en el panel de control de HyperPay.

Reembolsos

Los reembolsos desde PrestaShop no están admitidos, y los botones estándar de reembolso de PrestaShop no devuelven dinero a través de HyperPay. Reembolsa el pago en el panel de control de HyperPay y regístralo en PrestaShop con un reembolso parcial o una nota de crédito si hace falta. Los reembolsos y contracargos hechos en HyperPay se añaden al pedido como nota mediante el webhook; el estado del pedido no cambia.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox HyperPay Payment Gateway es el primer bloque de Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure, encima de los ajustes. Introduce 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-hyperpay y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del 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 y una fecha. Después de cambiar la dirección de la tienda, o después de liberar un hueco 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 solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Eliminar la clave de la tienda no libera su hueco de dominio. Libera el hueco en tu cuenta de vibefox.net.

Sin una clave activa, HyperPay 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 se siguen confirmando, y las capturas y los reembolsos funcionan.

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 después de introducir la clave y, después, una vez por semana. No se necesita ninguna tarea cron. Al desinstalar o restablecer el módulo, siempre se eliminan la clave de licencia y el estado de la licencia.

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, los reales en modo real. La página de ajustes muestra un aviso si faltan. En Payment > Preferences comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo de clientes.

El pago se completó, pero no se creó ningún pedido: 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 exista para el modo que usas, que su URL sea exactamente la que aparece en Webhook URL y que su clave de descifrado esté en el campo de clave de webhook del mismo modo. Activa Enable Logging y revisa el campo Log de la página del módulo.

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

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

El webhook responde Busy, retry later: otra solicitud estaba procesando el pedido en ese mismo momento, o el pedido no se pudo crear (por ejemplo, porque el módulo está desactivado). HyperPay reintenta el webhook. El motivo está en el registro.

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

La URL del webhook muestra Method not allowed en el navegador: es normal. La URL acepta solo solicitudes POST de HyperPay.

El formulario de pago no se carga: revisa el registro. 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 habilitadas para tu Entity ID.

El pedido está en HyperPay payment on hold: lee las notas del pedido (ver Estados de pedido), revisa el pago en el panel de control de HyperPay y, después, prepara el pedido o reembolsa el pago.

La captura falla: lee el código de resultado y la descripción en el bloque y en las notas. La captura se envía en el modo de la preautorización, así que deben estar configuradas las credenciales de ese modo; si no, el bloque indica que el Access Token / Entity ID de ese modo están vacíos.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox HyperPay Payment 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, la tabla de intentos de pago de HyperPay y los archivos de registro. Si está desactivado, todo se conserva para una reinstalación posterior. Los estados de pedido Awaiting HyperPay payment, HyperPay payment authorized y HyperPay payment on hold 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 titular. Este módulo no está afiliado ni respaldado por HyperPay.