VibeFox Worldline 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 Worldline: una cuenta de comerciante de Worldline Direct (antes Ingenico Direct). Las cuentas de prueba y reales son independientes y tienen credenciales distintas. Para cada cuenta necesitas el Merchant ID (tu PSPID), un API Key ID con su Secret API Key y una clave de webhook con su secreto. Todo se crea en el Merchant Portal de Worldline (véase «Configuración»).

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

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Payments > Worldline (Ingenico) > Manage, o haz clic en Settings debajo del nombre del plugin en la página de 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 las credenciales de prueba, guarda los ajustes y haz clic en Test credentials.

6. Añade la URL del webhook en el Merchant Portal de la cuenta de prueba e introduce la clave y el secreto del webhook (véase «Configuración»).

7. Activa Enable/Disable y haz un pago de prueba. Después introduce las credenciales reales, repite la configuración del webhook en tu cuenta real, haz clic en Live credentials y desmarca Test Mode.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Worldline (Ingenico). En la lista de métodos de pago, Worldline aparece marcado como que requiere configuración hasta que el modo actual tenga un Merchant ID, un API Key ID y un Secret API Key. En la página de ajustes, los campos de credenciales del modo que no se usa aparecen atenuados.

General

Enable/Disable: Enable Worldline 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: Worldline.

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

Worldline Direct API

Obtén las credenciales en el Merchant Portal de Worldline de la cuenta de prueba y de la cuenta real. Tu PSPID es el Merchant ID. Developer > Payment API crea el API Key ID y el Secret API Key, y Developer > Webhooks la clave y el secreto del webhook. La sección incluye enlaces a ambos portales y a la documentación de Worldline.

Test Mode: Enable test mode (pre-production environment, no real money) cambia tanto el endpoint de la API como las credenciales. El modo de prueba usa el entorno de preproducción y las credenciales de prueba; el modo real, el entorno de producción y las credenciales reales. Por defecto: activado. Desmárcalo para cobrar pagos reales. Mientras el modo de prueba esté activado, los clientes ven Test mode — no real money is charged. debajo del método de pago.

Cuenta de prueba (preproducción)

Test Merchant ID (PSPID): el PSPID de tu cuenta de prueba.

Test API Key ID: el API Key ID creado en Developer > Payment API de la cuenta de prueba.

Test Secret API Key: la Secret API Key que pertenece a ese API Key ID.

Test Webhook Key ID: opcional. Si se rellena, solo se aceptan los webhooks enviados con esta clave.

Test Webhook Secret: el secreto del webhook de la cuenta de prueba. Se usa para comprobar la firma de cada webhook.

Cuenta real (producción)

Live Merchant ID (PSPID): el PSPID de tu cuenta real.

Live API Key ID: el API Key ID creado en Developer > Payment API de la cuenta real.

Live Secret API Key: la Secret API Key que pertenece a ese API Key ID.

Live Webhook Key ID: opcional. Si se rellena, solo se aceptan los webhooks enviados con esta clave.

Live Webhook Secret: el secreto del webhook de la cuenta real.

Comprobar credenciales

Los botones Test credentials y Live credentials comprueban las credenciales guardadas de cada cuenta con una llamada de prueba a Worldline. Guarda primero los cambios. La respuesta aparece junto a los botones, por ejemplo Test credentials: connection successful., API credentials are not configured. o el error devuelto por Worldline.

Webhooks

El webhook informa a tu tienda de los pagos aunque el cliente no vuelva a la tienda, por ejemplo tras cerrar el navegador o cuando un pago se confirma más tarde. En el Merchant Portal abre Developer > Webhooks de la cuenta de prueba y añade la URL del endpoint que aparece en esta sección de los ajustes. Tiene este aspecto: https://your-site/wc-api/wlg_worldline_webhook/. Copia la URL exactamente como la muestran los ajustes: debe responder sin redirecciones, así que revisa los prefijos de idioma y las redirecciones forzadas a www o a https. Después introduce el ID y el secreto de la clave del webhook en Test Webhook Key ID y Test Webhook Secret. Haz lo mismo en la cuenta real con los campos reales.

El plugin responde automáticamente a la solicitud de verificación del endpoint de Worldline. Gestiona los eventos de pago (cambios de estado del pago) y los eventos de reembolso (cambios de estado del reembolso). Los demás eventos se aceptan y se ignoran. Los webhooks sin firma válida se rechazan. También se ignora un webhook que procede de un Merchant ID distinto del de la cuenta cuyo secreto firmó el webhook. Sin el webhook, un pedido solo se confirma cuando el cliente vuelve a la tienda tras pagar.

Página de pago y pedidos

Payment page template: nombre opcional de una plantilla (variante) de la página de pago alojada, subida al Merchant Portal, por ejemplo SimplifiedCustomPaymentPage. Déjalo vacío para usar la página predeterminada de Worldline.

Order Status After Payment: el estado del pedido una vez que Worldline confirma el pago capturado. El estado se aplica de inmediato, sin un segundo cambio de estado. Los pagos siempre se solicitan como venta directa (autorización y captura).

Logging: Enable debug logging escribe todas las solicitudes a la API y los webhooks en WooCommerce > Status > Logs, origen wcp_worldline_gateway. Los errores y las advertencias siempre se registran, también con esta opción desactivada. Las claves, los datos de tarjeta y los datos personales se enmascaran. Por defecto: desactivado.

Delete Data: Delete the plugin settings and logs when the plugin is deleted. Desactivar el plugin nunca borra nada. Los datos de pago guardados en los pedidos se conservan, porque son necesarios para los reembolsos. Por defecto: desactivado.

Al actualizar desde la versión 1.0, el antiguo conjunto único de credenciales se traslada a los campos de prueba o reales, según el modo que usaba la tienda.

Finalización de compra

El cliente elige el método de pago (por defecto Worldline) y realiza el pedido. El plugin crea una página de pago alojada de Worldline por el total del pedido en la moneda del pedido y envía al cliente a la página de pago de Worldline. Allí el cliente paga con tarjeta, con un monedero digital u otro método de pago habilitado en tu cuenta de Worldline. El nombre, la dirección, el correo electrónico y el teléfono de facturación se envían a Worldline, y la página de pago se abre en el idioma de tu tienda cuando Worldline lo admite. Cada intento de pago recibe su propia referencia, formada por el ID del pedido y una parte aleatoria.

Tras pagar, el cliente vuelve a tu tienda. El plugin comprueba el regreso frente al intento guardado y lee el estado del pago desde Worldline en el servidor. El pedido solo se marca como pagado cuando Worldline lo confirma: mediante esta comprobación de estado o mediante un webhook firmado. Entonces el cliente ve la página de pedido recibido.

Si el pago no se completó, el cliente pasa a la página Pay for order con un mensaje:

Un cliente puede volver a pagar un pedido no pagado desde la página Pay for order. Si el intento anterior se ha pagado entretanto, el cliente pasa directamente a la página de pedido recibido y no se le cobra dos veces. Si la página de pago anterior sigue abierta para el mismo importe y modo y se creó hace menos de 30 minutos, el cliente vuelve a ella.

Si Worldline no puede iniciar el pago, el cliente ve Payment error: Could not create checkout session. Please try again. y puede elegir otro método de pago. El motivo se añade a las notas del pedido y al registro. Si faltan las credenciales del modo actual, el cliente ve This payment method is not available at the moment. Please choose another payment method.

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 WooCommerce High-Performance Order Storage (HPOS).

El plugin acepta pagos únicos como venta directa en la página de Worldline. No tiene tarjetas guardadas ni tokenización, suscripciones, formulario de tarjeta integrado, modo solo de autorización con captura o anulación desde WooCommerce, recargos ni registro automático de webhooks.

Pedidos y reembolsos

Order statuses

Pending payment: el cliente fue enviado a Worldline y aún no ha pagado, o Worldline aún no ha confirmado el pago. Una nota muestra el ID de la página de pago alojada, la referencia y el modo (prueba o real).

Processing or Completed: el pago fue capturado. El estado sigue a Order Status After Payment. La nota del pedido muestra el importe, el ID del pago de Worldline y cómo se confirmó (webhook firmado o comprobación del estado). El ID de transacción del pedido es el ID del pago de Worldline.

On hold, waiting for capture: Worldline indica que el pago está autorizado o que la captura está solicitada, pero aún no capturada. La nota del pedido lo explica. El pedido se marca como pagado automáticamente cuando el webhook confirma la captura. Si la nota dice que el pago no está capturado, captúralo en el Merchant Portal de Worldline.

On hold, held for manual review: el pago no coincide con el pedido, por ejemplo porque el importe o la moneda son distintos (el pedido se editó después de iniciar el pago) o porque el pago pertenece a otro intento. La nota muestra el importe pagado, el total del pedido y la referencia. Revisa el pedido y tramítalo, o reembolsa el pago.

Failed: Worldline rechazó o canceló el pago del último intento, o el cliente no era apto para el método de pago elegido.

Cancelled: el pedido lo cancelaste tú o el tiempo de espera de la reserva de existencias de WooCommerce. Si llega un pago para un pedido cancelado o reembolsado, el pedido no se reabre. Una nota te pide reembolsar o cancelar el pago en el Merchant Portal de Worldline, o restaurar el pedido manualmente. El cliente que regresa ve Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment.

Si llega un segundo pago para un pedido que ya está pagado, el pedido no se vuelve a modificar. Una nota te pide reembolsar el segundo pago en el Merchant Portal de Worldline.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Worldline (Ingenico). Se admiten reembolsos totales y parciales. El pago debe estar capturado. El reembolso siempre se envía al entorno del pago original (prueba o real) con las credenciales de esa cuenta, así que deben estar configuradas. Un reembolso que se reintenta tras un tiempo de espera no se ejecuta dos veces. Si Worldline rechaza el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso aceptado se añade a las notas del pedido con el ID y el estado del reembolso de Worldline.

Los cambios de estado de los reembolsos llegan desde Worldline mediante webhook y se añaden a las notas del pedido. Los reembolsos hechos en el Merchant Portal no se registran automáticamente como reembolsos de WooCommerce. Si es necesario, crea un reembolso manual en WooCommerce sin usar Refund via Worldline (Ingenico).

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 > Worldline (Ingenico). 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 eliminarla 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 su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Worldline 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 administradores 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 de 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

Worldline 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 un Merchant ID, un API Key ID y un Secret API Key: los campos de prueba en modo de prueba, los campos reales en modo real. La lista de pagos marca el método como pendiente de configuración si faltan.

El pago se hizo, pero el pedido sigue en Pending payment: el webhook no funciona. En el Merchant Portal de la cuenta que usas (prueba o real), comprueba que el endpoint existe y que su URL es exactamente la que aparece en los ajustes, sin redirecciones. Comprueba que el secreto del webhook de esa cuenta está en el campo correspondiente (Test Webhook Secret o Live Webhook Secret) y que Webhook Key ID está vacío o coincide con la clave. El pedido también se confirma cuando el cliente vuelve a la tienda tras pagar.

El webhook responde «Webhook secret not configured»: no hay ningún secreto de webhook configurado. Introduce el secreto del webhook en los ajustes. Worldline reintenta el webhook.

El webhook responde «Invalid signature»: el secreto del webhook pertenece a otra cuenta u otra clave, o Webhook Key ID no coincide con la clave que envió el webhook.

El webhook responde «Missing signature», «Empty body» o «Invalid JSON»: la solicitud no llegó desde Worldline en el formato esperado, o un proxy o una redirección la modificó. Comprueba que la URL responde sin redirecciones.

El webhook responde «Ignored»: el webhook procede de un Merchant ID distinto del configurado en los ajustes de ese modo. Revisa Test Merchant ID (PSPID) o Live Merchant ID (PSPID).

El webhook responde «Retry later»: otra solicitud estaba actualizando el pedido en ese mismo momento. Worldline reintenta el webhook.

Test credentials o Live credentials muestra un error: guarda primero los ajustes y comprueba que el Merchant ID, el API Key ID y el Secret API Key proceden de la misma cuenta, y que los valores de prueba están en los campos de prueba y los valores reales en los campos reales.

El cliente ve un error al realizar el pedido: abre las notas del pedido o WooCommerce > Status > Logs, origen wcp_worldline_gateway. Los errores se registran aunque el registro de depuración esté desactivado. Para ver todos los detalles de las solicitudes, activa Logging y vuelve a intentarlo.

Los pagos de prueba no confirman un pedido real: las pruebas y las operaciones reales están separadas. Un webhook firmado con el secreto de prueba nunca confirma un intento de pago real, y viceversa. Cambia Test Mode al modo que quieras usar y utiliza las credenciales y el webhook de esa cuenta.

El pedido está en On hold tras el pago: lee la nota del pedido. O bien Worldline aún no ha confirmado la captura (el webhook completa el pedido), o el importe o la moneda pagados no coincidían con el pedido.

El reembolso falla con un mensaje sobre el entorno: el pago se hizo en el entorno de prueba o en el real, y las credenciales de ese entorno no están configuradas. Introdúcelas y vuelve a intentarlo.

Desarrolladores: el filtro wlg_hosted_checkout_data modifica la solicitud de la página de pago alojada, por ejemplo para limitar los métodos de pago que se muestran, y wlg_gateway_icon cambia el icono del método de pago.

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.

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 la licencia de este plugin siempre se eliminan. Los ajustes de la pasarela y los registros solo se eliminan si Delete Data estaba activado; en caso contrario, se conservan para una reinstalación posterior. Los datos de pago de Worldline guardados en los pedidos siempre se conservan, porque son necesarios para los reembolsos. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Worldline es una marca comercial de su respectivo titular. Este plugin no está afiliado a Worldline ni cuenta con su aprobación.