VibeFox Adyen for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

Cuenta de Adyen: necesitas el nombre de tu cuenta de comerciante de Adyen, una clave de API y una clave HMAC para cada entorno que uses (prueba y producción) y, para pagos reales, el prefijo de URL de producción. La clave de API pertenece a una credencial de API con los roles Checkout webservice y Merchant PAL webservice. La clave HMAC se genera para el webhook Standard (véase Configuración). El Área de cliente de prueba es ca-test.adyen.com y la de producción es ca-live.adyen.com. Las claves de prueba y de producción son independientes. No se necesita clave de cliente, porque la página de pago está alojada por Adyen.

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 adelante VibeFox Adyen Gateway en la lista de módulos y haz clic en Configure.

3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página de configuración del módulo, y haz clic en Activate (ver Clave de licencia).

4. Introduce tu cuenta de comerciante, la clave de API de prueba y la clave HMAC de prueba y, más adelante, la clave de API de producción, la clave HMAC de producción y el prefijo de URL de producción.

5. En el Área de cliente de Adyen (prueba y producción) añade un webhook Standard con la URL que aparece en la sección Webhook del módulo (véase Configuración).

6. Activa Enable/Disable y haz clic en Save. Prueba un pago con Test mode activado y después desactívalo.

Al instalarse, el módulo crea el estado de pedido Adyen payment on hold. PrestaShop habilita el módulo de pago para las monedas, los países y los grupos de clientes que estén activos en ese momento. Revísalos y cámbialos en Payment > Preferences; los países que añadas después deben marcarse allí.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Adyen Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Mientras los ajustes del modo actual estén incompletos, la página muestra Adyen is hidden at checkout until the test settings are complete (o los de producción) y enumera lo que falta: Merchant account, la clave de API, la clave HMAC y, en modo de producción, Live URL prefix. Mientras el modo de prueba esté activado, la página muestra Test mode is on: payment links and refunds go to the Adyen test environment, no real money. Al guardar, una clave HMAC que no sea hexadecimal y un prefijo de URL de producción con caracteres distintos de letras, dígitos y guiones no se guardan: aparece una advertencia que indica el campo y se conserva el valor anterior.

Adyen

Enable/Disable: Enable Adyen payment gateway activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: Adyen. Obligatorio.

Description: el texto que aparece debajo del método de pago en la finalización de compra. Predeterminado: Pay securely via Adyen.

Cuenta de Adyen

Las claves de API se crean en el Área de cliente de Adyen, en Developers > API credentials. Rellena ambos conjuntos de claves; el interruptor Test mode selecciona cuál se usa.

Test mode: usa el entorno de prueba de Adyen (sin dinero real). Cuando está activado, los enlaces de pago y los reembolsos van a checkout-test.adyen.com con la clave de API de prueba. Predeterminado: activado. Desactívalo para cobrar pagos reales. Mientras esté activado, los clientes ven Test mode: no real payment is taken. debajo del método de pago.

Merchant account: el nombre de tu cuenta de comerciante de Adyen (no la cuenta de la empresa), por ejemplo MyShopECOM. Suele ser el mismo en el Área de cliente de prueba y en la de producción.

Credenciales de prueba

Se usan mientras Test mode está activado.

Test API key: desde el Área de cliente de prueba: Developers > API credentials > tu credencial > API key.

Test HMAC key: desde el Área de cliente de prueba: Developers > Webhooks > tu webhook Standard > HMAC key (hexadecimal). Obligatoria: los webhooks sin una firma válida se rechazan.

Credenciales de producción

Se usan cuando Test mode está desactivado.

Live API key: desde el Área de cliente de producción: Developers > API credentials > tu credencial > API key.

Live HMAC key: desde el Área de cliente de producción: Developers > Webhooks > tu webhook Standard > HMAC key (hexadecimal).

Live URL prefix: desde el Área de cliente de producción: Developers > API URLs, por ejemplo 1797a841fbb37ca7-AdyenDemo, a partir de https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. Puedes pegar la URL completa; el prefijo se toma de ella al guardar.

Las claves de API y las claves HMAC guardadas nunca se vuelven a mostrar. El campo queda vacío y su indicación termina con Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.

Clear saved secrets: marca una clave y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.

Webhook

Los pedidos solo los crean los webhooks de Adyen. En el Área de cliente (prueba y producción) ve a Developers > Webhooks y añade un Standard webhook con la URL que aparece en Webhook URL en esta sección. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_adyen_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como aparece en los ajustes, porque Adyen no sigue redirecciones. Elige el método JSON, activa Generate HMAC key y copia la clave en Test HMAC key o en Live HMAC key.

El entorno de cada notificación selecciona la clave HMAC, y una notificación solo se aplica a un enlace de pago creado en el mismo entorno y con la misma cuenta de comerciante. Una notificación de prueba nunca confirma un pago real. Los webhooks sin una firma válida se rechazan con HTTP 401, y Adyen los reintenta más tarde. Sin el webhook no se crea ningún pedido.

El módulo gestiona estos eventos:

Los demás eventos se añaden a las notas del pedido. Las notificaciones que no corresponden a un carrito de esta tienda, por ejemplo el botón de prueba del Área de cliente, se aceptan e ignoran. El webhook funciona mientras la tienda está en modo de mantenimiento y no lo bloquea la restricción por país de tu tienda.

Avanzado

Order status after payment: el estado del pedido que establece un webhook AUTHORISATION correcto.

Los errores de importe o de moneda y las capturas fallidas siempre pasan a Adyen payment on hold.

Debug log: escribe las llamadas a la API y los eventos de webhook en logs/adyg_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran, aunque el interruptor esté desactivado. El registro nunca contiene claves de API ni claves HMAC ni datos personales de los clientes. Predeterminado: 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 del módulo, los registros de pagos de Adyen (referencias PSP, eventos de webhook, reembolsos) y los registros. El estado de pedido Adyen payment on hold y los pedidos se conservan. Predeterminado: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto Adyen) y ve la nota You will be redirected to Adyen to complete the payment securely. Al confirmar, el módulo crea un enlace de pago de Adyen por el total del carrito en la moneda del carrito y envía al cliente a la página de pago de Adyen. Allí el cliente paga con cualquier método activado en tu cuenta de Adyen. El correo electrónico, el nombre y el país de facturación del cliente, así como el idioma de la tienda, se pasan a Adyen, y el pago aparece como Cart # seguido del número del carrito. Todavía no existe ningún pedido en este punto.

Tras pagar, el cliente vuelve a tu tienda. El regreso en sí no crea ni paga ningún pedido: el pedido se marca como pagado solo cuando Adyen lo confirma con el webhook AUTHORISATION firmado y el importe y la moneda coinciden con el carrito. Si el webhook ya ha llegado, el cliente ve la página estándar de confirmación del pedido con Your payment with Adyen has been received. (o Your payment with Adyen has been received and is being reviewed by the store. para un pedido en espera). Si Adyen canceló el pago antes de eso, la página muestra Your Adyen payment was not completed. Please contact us about this order. Si el webhook aún no ha llegado, una página de Payment confirmation muestra Your payment is being confirmed by Adyen. Your order will be created as soon as Adyen confirms the payment, and you will receive an e-mail. con los botones Check again y Back to checkout, para el cliente que no completó el pago.

Si el pago es rechazado, no se crea ningún pedido y el cliente puede volver a intentarlo. Cuando el cliente inicia un nuevo pago para el mismo carrito, el enlace de pago anterior caduca y ya no puede pagarse. Si el carrito ya tiene un pedido, el cliente va a la confirmación de ese pedido en lugar de a un nuevo pago.

Si no se puede crear el enlace de pago, el cliente se queda en la finalización de compra con Payment could not be initiated. Please try again or choose another payment method. El motivo se escribe en el registro. Si los ajustes están incompletos, el mensaje es Payment gateway is not configured properly. Please contact the store administrator.

Los desarrolladores pueden modificar la solicitud del enlace de pago con el hook actionAdygPaymentLinkRequest.

El módulo no tiene suscripciones ni pagos recurrentes, no guarda tarjetas, no tiene campos de tarjeta en el sitio (Drop-in o Components), no tiene botones de captura o cancelación en PrestaShop y no usa autenticación básica para los webhooks.

Pedidos y reembolsos

Estados del pedido

No order yet: el cliente fue enviado a Adyen y no ha pagado, el pago fue rechazado o Adyen aún no ha confirmado el pago. Solo existe el carrito.

Payment accepted, Delivered or Adyen payment on hold: el pago fue autorizado. El estado depende de Order status after payment. El pago se registra con la referencia PSP de Adyen como ID de transacción, y una nota muestra el importe, la referencia PSP y el método de pago.

Adyen payment on hold after payment: Adyen confirmó un importe o una moneda distintos del total del carrito (por ejemplo, el carrito se modificó después de iniciar el pago), una captura falló o el pago llegó después de que el pedido se hubiera cancelado. La nota lo explica. Comprueba el pago en el Área de cliente y después tramita el pedido o reembolsa el pago.

Canceled: el pago de este pedido fue cancelado en Adyen.

Refunded: el pago fue reembolsado por completo a través del módulo.

Si llega un segundo pago correcto para un pedido que ya está pagado, por ejemplo desde un enlace de pago antiguo, el pedido no cambia. Una nota te pide que compruebes en el Área de cliente si hay un cargo duplicado y que lo reembolses allí si es necesario.

Bloque de pago de Adyen

La página del pedido muestra un bloque Adyen payment con la referencia PSP, el enlace de pago, la cuenta de comerciante y el entorno, el estado del pago, el importe pagado y reembolsado, una insignia Test mode para los pagos de prueba, el historial de reembolsos y las Adyen notes: las notas que el módulo añade al pedido (pago autorizado, diferencia de importe, pago duplicado, captura, cancelación, resultados de reembolsos), de la más reciente a la más antigua. Estas notas son mensajes privados del pedido; PrestaShop 8.2 y 9 no las muestran en ningún otro lugar de la página del pedido.

Reembolsos

En el bloque Adyen payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Adyen. Confirma la pregunta Refund this amount through Adyen? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos. Los reembolsos se hacen por el importe y en la moneda que autorizó Adyen, así que tras una diferencia de importe o de moneda puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía al entorno y a la cuenta de comerciante con los que se hizo el pago, por lo que la clave de API de ese entorno debe estar configurada. Si Adyen no acepta la solicitud, el bloque muestra el error y no se registra ningún reembolso.

Adyen procesa los reembolsos de forma asíncrona: la solicitud se añade al historial de reembolsos y a las notas con el estado received, y el resultado final llega mediante el webhook REFUND o REFUND_FAILED. Un reembolso fallido ya no cuenta como reembolsado. Cuando los reembolsos enviados alcanzan el importe pagado, el pedido pasa a Refunded. Un reembolso parcial no cambia el estado. Con captura manual en Adyen, solo se pueden reembolsar los pagos capturados.

El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de Adyen. Los reembolsos hechos en el Área de cliente de Adyen llegan mediante webhook y se añaden a las notas. El estado del pedido y las facturas de abono no se cambian automáticamente.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Adyen Gateway es el primer bloque de Modules > Module Manager > VibeFox Adyen Gateway > Configure, por 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-adyen 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 acceder al 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. Quitar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Adyen 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 los reembolsos funcionan.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan 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 a la 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

Adyen no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que los ajustes del modo actual estén completos: Merchant account, la clave de API y la clave HMAC de ese modo y, en modo de producción, Live URL prefix. La página de ajustes enumera lo que falta. En Payment > Preferences comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo del cliente.

El pago se realizó, pero no se creó ningún pedido: el webhook no funciona. En el Área de cliente del entorno que usas (prueba o producción) comprueba que existe el webhook Standard, que su URL es exactamente la que aparece en Webhook URL y que el método es JSON. Comprueba que la clave HMAC de ese webhook está en el campo correspondiente (Test HMAC key o Live HMAC key). Con una clave HMAC no válida o ausente, el módulo responde HTTP 401 y Adyen reintenta la entrega más tarde, así que el pedido se crea automáticamente una vez corregida la clave. El registro muestra Webhook rejected: invalid HMAC signature o que la clave HMAC no está configurada.

El webhook responde [rejected] HMAC key not configured: la clave HMAC del entorno de la notificación está vacía. Pégala en los ajustes.

El webhook responde [rejected] busy, retry later: otra entrega estaba procesando el carrito en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Adyen reintenta el webhook automáticamente. El motivo está en el registro.

La URL del webhook muestra [rejected] POST required in the browser: es normal. La URL solo acepta notificaciones de Adyen.

La advertencia de la clave HMAC al guardar: el campo debe contener la clave HMAC hexadecimal del Área de cliente. Se conservó el valor anterior.

El cliente ve Payment could not be initiated: revisa el campo Log de la página del módulo (los errores siempre se registran). Comprueba la clave de API, la cuenta de comerciante y, en modo de producción, el prefijo de URL de producción.

El pedido está en Adyen payment on hold tras el pago: lee la nota del pedido. El importe o la moneda confirmados por Adyen no coincidían con el carrito, una captura falló o el pago llegó después de una cancelación. También puede deberse al ajuste Order status after payment.

El reembolso falla: el pedido debe tener una referencia PSP de Adyen, que llega con el webhook AUTHORISATION. Deben estar configuradas las credenciales del entorno en el que se hizo el pago; de lo contrario, el bloque indica que las credenciales no están configuradas. Con captura manual, solo se pueden reembolsar los pagos capturados.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Adyen 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 del módulo, los registros de pagos de Adyen (referencias PSP, eventos de webhook, reembolsos) y los registros. Si está desactivado, todos ellos se conservan para una reinstalación posterior, de modo que los pedidos pagados antes pueden seguir reembolsándose. El estado de pedido Adyen payment on hold siempre permanece. Los pedidos existentes conservan sus notas de pago y sus IDs de transacción.

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