VibeFox Adyen for WooCommerce — Ayuda

Requisitos

WordPress: 6.0 o posterior.

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

PHP: 8.0 o posterior.

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 (consulta Configuración). El Customer Area de prueba es ca-test.adyen.com, y el de producción, ca-live.adyen.com. Las claves de prueba y de producción son independientes.

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_adyen_gateway a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre la configuración: WooCommerce > Settings > Payments > Adyen > 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 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.

6. En el Customer Area (prueba y producción) añade un webhook Standard con la URL que muestra la configuración del plugin (consulta Configuración).

7. Activa Enable/Disable. Prueba un pago con Test mode activado y, después, desmárcalo.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Adyen. 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. 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 se rechazan con un error, y se mantiene el valor anterior.

General

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

Title: el nombre del método de pago que ven los clientes en la finalización de compra. Por defecto: Adyen.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely via Adyen.

Cuenta de Adyen

Las claves de API se crean en el Customer Area de Adyen, en Developers > API credentials. Introduce ambos conjuntos de claves; el interruptor Test mode decide cuál se usa.

Test mode: Use the Adyen test environment (no real money). Cuando está activado, los enlaces de pago y los reembolsos van a checkout-test.adyen.com con la clave de API de prueba. Por defecto: activado. Desmárcalo para aceptar pagos reales.

Merchant account: el nombre de tu cuenta de comerciante de Adyen (no la cuenta de empresa), por ejemplo MyShopECOM. Normalmente es el mismo en el Customer Area de prueba y en el de producción.

Credenciales de prueba

Se usan mientras Test mode está activado.

Test API key: del Customer Area de prueba: Developers > API credentials > tu credencial > API key.

Test HMAC key: del Customer Area de prueba: Developers > Webhooks > tu webhook Standard > HMAC key (hexadecimal). Es obligatoria: los webhooks sin una firma válida se rechazan.

Credenciales de producción

Se usan cuando Test mode está desactivado.

Live API key: del Customer Area de producción: Developers > API credentials > tu credencial > API key.

Live HMAC key: del Customer Area de producción: Developers > Webhooks > tu webhook Standard > HMAC key (hexadecimal).

Live URL prefix: del Customer Area de producción: Developers > API URLs, por ejemplo 1797a841fbb37ca7-AdyenDemo de https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. Puedes pegar la URL completa; el prefijo se extrae de ella al guardar.

Webhook

Los pedidos solo se marcan como pagados mediante webhooks de Adyen. En el Customer Area (prueba y producción) ve a Developers > Webhooks y añade un Standard webhook con la URL que aparece en esta sección de los ajustes. Tiene el aspecto de https://your-site/wc-api/adyg_adyen_webhook/. Elige JSON como método, activa Generate HMAC key y copia la clave en Test HMAC key o en Live HMAC key. El entorno de cada notificación determina la clave HMAC que se usa. Los webhooks sin una firma válida se rechazan, y Adyen los reintenta más tarde. Sin el webhook, los pedidos permanecen en Pending payment.

El plugin gestiona estos eventos:

Los demás eventos se añaden a las notas del pedido. Las notificaciones que no corresponden a un pedido de esta tienda, por ejemplo el botón de prueba del Customer Area, se aceptan y se ignoran.

Avanzado

Order status after payment: el estado del pedido que se asigna tras un pago correcto, en un único cambio de estado.

Debug log: Log API calls and webhook events escribe en WooCommerce > Status > Logs, origen wcp_adyen_gateway. Los errores siempre se registran. Los registros nunca contienen claves de API ni HMAC, ni datos personales de los clientes. Por defecto: desactivado.

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted. Por defecto: desactivado.

Finalizar compra

El cliente elige el método de pago (por defecto, Adyen) y realiza el pedido. El plugin crea un enlace de pago de Adyen por el total del pedido en la moneda del pedido 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. Se envían a Adyen el correo electrónico, el nombre y el país de facturación del cliente y el idioma de la tienda, y el pago aparece como Order # y el número del pedido.

Tras pagar, el cliente vuelve a la página de pedido recibido de tu tienda. El regreso en sí no marca el pedido como pagado: el pedido solo se marca como pagado cuando Adyen lo confirma mediante el webhook firmado AUTHORISATION y el importe y la moneda coinciden con el pedido.

Si el pago se rechaza, el pedido pasa a Failed y el cliente puede volver a intentarlo. Cuando el cliente inicia un nuevo pago para el mismo pedido, por ejemplo desde la página Pay for order, el enlace de pago anterior caduca y ya no se puede pagar.

Si no se puede crear el enlace de pago, el cliente ve Payment could not be initiated. Please try again or choose another payment method. El motivo se añade a las notas del pedido. Si los ajustes están incompletos, el cliente ve Payment gateway is not configured properly. Please contact the store administrator.

Para las monedas sin decimales, como JPY, KRW, IDR o VND, define WooCommerce > Settings > General > Number of decimals en 0. Si no, el total se redondea a una unidad entera.

El método de pago funciona en la finalización de compra clásica y en el bloque de Finalizar compra. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).

El plugin 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 ni de cancelación en WooCommerce y no admite autenticación básica para los webhooks.

Pedidos y reembolsos

Estados del pedido

Pending payment: se creó el enlace de pago y Adyen todavía no ha confirmado el pago. La nota del pedido muestra el enlace de pago, el importe y el entorno.

Processing, Completed or On Hold: el pago fue autorizado. El estado sigue a Order status after payment. La nota del pedido muestra el importe, la referencia PSP y el método de pago. El ID de la transacción es la referencia PSP de Adyen.

On hold after payment: Adyen confirmó un importe o una moneda distintos al total del pedido. La nota del pedido muestra ambos valores, y el pedido no se marca como pagado. Un pedido pagado también pasa a espera cuando falla una captura, porque el dinero no se cobró. Revisa el pago en el Customer Area.

Failed: el pago fue rechazado. Los pedidos pagados, en espera y cancelados no se modifican con un pago rechazado.

Cancelled: el pago de este pedido se canceló en Adyen.

Si llega un segundo pago correcto para un pedido que ya está pagado, por ejemplo desde un enlace de pago antiguo, el pedido no se vuelve a modificar. Una nota te pide que revises el Customer Area por si hay un cargo duplicado y que, si es necesario, hagas el reembolso allí.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Adyen. Se admiten reembolsos totales y parciales. 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. Adyen procesa los reembolsos de forma asíncrona: la solicitud se anota en el pedido y el resultado final se añade como nota mediante el webhook REFUND o REFUND_FAILED. Si Adyen no acepta la solicitud, WooCommerce muestra el error y no se registra ningún reembolso. Con captura manual en Adyen, solo se pueden reembolsar los pagos capturados.

Los reembolsos hechos en el Customer Area de Adyen llegan mediante webhook y se añaden a las notas del pedido. No se registran automáticamente como reembolsos de 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 > Adyen. 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 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. 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 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 los reembolsos 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

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.

El pago se realizó, pero el pedido sigue en Pending payment: el webhook no funciona. En el Customer Area del entorno que usas (prueba o producción) comprueba que existe el webhook Standard, que su URL es exactamente la que aparece en los ajustes y que el método es JSON. Comprueba también que la clave HMAC de ese webhook esté en el campo correspondiente (Test HMAC key o Live HMAC key). Con una clave HMAC incorrecta o ausente, el plugin responde HTTP 401 y Adyen reintenta la entrega más tarde, así que el pedido se actualiza automáticamente cuando se corrige la clave. El registro muestra Webhook rejected: invalid HMAC signature o que la clave HMAC no está configurada.

El webhook responde con busy, retry later: el pedido estaba siendo procesado por otra entrega en el mismo momento. Adyen reintenta el webhook automáticamente.

Error de la clave HMAC al guardar: el campo debe contener la clave HMAC hexadecimal del Customer Area. Se mantuvo el valor anterior.

El cliente ve el mensaje Payment could not be initiated: revisa las notas del pedido o activa el Debug log y mira en WooCommerce > Status > Logs, origen wcp_adyen_gateway. Comprueba la clave de API, la cuenta de comerciante y, en modo de producción, el prefijo de URL de producción.

El pedido queda en On hold tras el pago: lee la nota del pedido. El importe o la moneda que confirmó Adyen no coincidían con el pedido, o falló una captura. También puede deberse a la configuración de 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. Con captura manual, solo se pueden reembolsar los pagos capturados.

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 para el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.

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 y los datos de Adyen guardados en los pedidos (referencias PSP, enlaces de pago y eventos procesados) solo se eliminan si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago e ID de transacción.

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