VibeFox Worldline for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.
Cuenta de Worldline: una cuenta de comerciante de Worldline Direct (antes Ingenico Direct). Las cuentas de prueba y real 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. Todas se crean 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 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 Worldline Gateway en la lista de módulos y haz clic en Configure.
3. Pega tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. Introduce las credenciales de prueba, haz clic en Save y después en Test credentials.
5. 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).
6. 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 desactiva Test Mode.
Al instalarse, el módulo crea dos estados de pedido: Awaiting Worldline capture y Worldline payment on hold. PrestaShop activa un nuevo módulo de pago para los países que están activos en ese momento. Revisa las monedas, los países y los grupos de clientes en Payment > Preferences, y marca allí los países que añadas más adelante.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Worldline Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa si las credenciales del modo actual (Merchant ID, API Key ID, Secret API Key) están incompletas, porque entonces el método de pago se oculta en la finalización de compra. Mientras el modo de prueba está activado, la página muestra Test mode is on (pre-production environment): no real money is charged.
Worldline (Ingenico)
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 ve el cliente en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Worldline. Obligatorio.
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 crea la clave y el secreto del webhook. La sección incluye enlaces a ambos portales y a la documentación de Worldline.
Test Mode: cambia a la vez el endpoint de la API y 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. Desactívalo 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: el 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: el 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.
Las claves secretas y los secretos 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.
Clear saved secrets: marca un secreto y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.
Check credentials: los botones Test credentials y Live credentials comprueban las credenciales guardadas de cada cuenta mediante una llamada de prueba a Worldline. Guarda primero tus cambios. La respuesta aparece en la parte superior de la página, por ejemplo Test credentials: connection successful., API credentials are not configured. o el error que devuelva Worldline.
Webhooks
El webhook informa a tu tienda de los pagos aunque el cliente no vuelva a ella, por ejemplo después de 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 que aparece en Endpoint URL de esta sección. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_worldline_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como la muestran los ajustes: debe responder sin redirecciones. 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 módulo responde automáticamente a la solicitud de verificación del endpoint de Worldline. Gestiona los eventos de pago (cambios de estado de los pagos) y los eventos de reembolso (cambios de estado de los reembolsos). Los demás eventos se aceptan y se ignoran. Los webhooks sin una firma válida se rechazan. Un evento debe estar firmado con el secreto de la cuenta en la que se hizo el pago, así que un webhook de prueba nunca confirma un pago real. Un webhook también se ignora si procede de un Merchant ID distinto al de la cuenta cuyo secreto lo firmó. Sin el webhook, un pedido solo se crea cuando el cliente vuelve a la tienda después de pagar.
Página de pago y pedidos
Payment page template: nombre opcional de una plantilla (variante) de la página de pago alojada, subida en el 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. Los pagos siempre se solicitan como venta directa (autorización y captura).
Los pagos autorizados esperan en Awaiting Worldline capture. Las diferencias de importe o de moneda siempre pasan a Worldline payment on hold.
Avanzado
Logging: escribe todas las solicitudes a la API y los webhooks en logs/wlg_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran, aunque esta opción esté desactivada. Las claves, los datos de tarjeta y los datos personales se enmascaran. 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: si está activado, al desinstalar el módulo se eliminan sus ajustes y el registro. Las transacciones y los reembolsos de Worldline y los estados de pedido del módulo siempre se conservan, porque los pedidos existentes los necesitan para los reembolsos. Por defecto: desactivado.
Finalizar compra
En el paso de pago, el cliente elige el método de pago (por defecto Worldline) y confirma. El módulo crea una página de pago alojada de Worldline por el total del carrito en la moneda del carrito 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 de facturación, la dirección, el correo electrónico y el teléfono se envían a Worldline, y la página de pago se abre en el idioma del cliente cuando Worldline lo admite. Cada intento de pago recibe su propia referencia, formada por el ID del carrito y una parte aleatoria. En este punto todavía no existe ningún pedido.
Tras pagar, el cliente vuelve a tu tienda. El módulo comprueba el regreso frente al intento guardado y lee el estado del pago en Worldline desde el servidor. El pedido se marca como pagado solo cuando Worldline lo confirma, mediante esa comprobación de estado o mediante un webhook firmado. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your payment with Worldline has been received. Si el pago está autorizado pero aún no capturado, la página muestra Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. Si después falla el pago de un pedido así, la página muestra Your Worldline payment was not completed. Please contact us about this order.
Si el pago no se completó, no se crea ningún pedido, el carrito se conserva y el cliente vuelve a la finalización de compra con un mensaje:
Si todavía no se pudo comprobar el estado, una página Payment confirmation muestra We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it. con los botones Check again y Back to checkout. El webhook crea el pedido en cuanto llega.
Cuando el cliente paga de nuevo el mismo carrito, el módulo comprueba primero el intento anterior. Si entretanto se ha pagado, el cliente pasa directamente a la confirmación del pedido 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 se queda en la finalización de compra con Payment error: Could not create checkout session. Please try again. El motivo se escribe en el 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 webhook funciona mientras la tienda está en modo de mantenimiento y no está bloqueado por la restricción de países de tu tienda.
El módulo acepta pagos únicos como venta directa en la página de Worldline. No incluye tarjetas guardadas ni tokenización, suscripciones, formulario de tarjeta integrado, modo solo de autorización con captura o anulación desde PrestaShop, recargos ni registro automático de webhooks.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a Worldline y no ha pagado, o Worldline todavía no ha confirmado el pago. Solo existe el carrito.
Payment accepted or Delivered: el pago se capturó. El estado sigue a Order Status After Payment. El pago se registra con el ID de pago de Worldline como ID de transacción, y una nota muestra el importe, el ID de pago y la forma en que se confirmó (webhook firmado o comprobación de estado).
Awaiting Worldline capture: Worldline informa de que el pago está autorizado o de que la captura está solicitada, pero todavía no capturada. Aún no se registra ningún pago. El pedido pasa al estado pagado cuando el webhook confirma la captura. Si la nota indica que el pago no está capturado, captúralo en el Merchant Portal de Worldline.
Worldline payment on hold: el pago no coincide con el carrito, por ejemplo porque el importe o la moneda son distintos (el carrito se cambió 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.
Payment error: Worldline rechazó o canceló el pago de un pedido que esperaba la captura.
Refunded: el pago se reembolsó por completo a través del módulo.
Si llega un pago para un pedido cancelado o reembolsado, el pedido no se reabre. Una nota te pide que reembolses o canceles el pago en el Merchant Portal de Worldline, o que restaures 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 cambia. Una nota te pide que reembolses el segundo pago en el Merchant Portal de Worldline.
Bloque de pago de Worldline
La página del pedido muestra un bloque Worldline payment con el ID de pago, la referencia del comerciante, la página de pago alojada, el estado del intento, el importe cobrado y el importe reembolsado, una etiqueta Test environment para los pagos de prueba, el historial de reembolsos y las Payment notes del pedido.
Reembolsos
En el bloque Worldline payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Worldline. Confirma la pregunta Refund this amount through Worldline? This cannot be undone. Se admiten reembolsos totales y parciales. El pago debe estar capturado. Necesitas el derecho a editar pedidos; no hace falta acceso a las páginas de módulos. Los reembolsos se hacen por el importe y en la moneda que cobró Worldline, 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 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, y solo se ejecuta un reembolso de un pedido a la vez. Si Worldline rechaza el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso aceptado se añade al historial de reembolsos y a las notas, con el ID y el estado del reembolso de Worldline. Un reembolso total cambia el pedido a Refunded. Un reembolso parcial no cambia el estado.
El módulo no crea facturas de abono. Los botones estándar de reembolso de PrestaShop en la página del pedido no devuelven dinero a través de Worldline.
Los cambios de estado de los reembolsos de Worldline llegan por webhook, actualizan el historial de reembolsos y se añaden a las notas. Los reembolsos hechos en el Merchant Portal no cambian el estado del pedido ni crean facturas de abono. Actualízalos manualmente si es necesario.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Worldline Gateway es el primer bloque de Modules > Module Manager > VibeFox Worldline Gateway > Configure, por encima de la configuración. Pega 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-worldline 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 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 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 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 se inicia un pago de todos modos, 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 después de introducir la clave y después una vez a la semana. No se necesita ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
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 Merchant ID, API Key ID y Secret API Key: los campos de prueba en modo de prueba, los campos reales en modo real. La página de ajustes muestra una advertencia 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 del cliente.
El pago se realizó, pero no se creó ningún pedido: 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 Endpoint URL, 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 el campo del ID de la clave del webhook está vacío o coincide con la clave. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar.
Si 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.
Si el webhook responde Invalid signature: el secreto del webhook pertenece a otra cuenta u otra clave, o el ID de la clave del webhook no coincide con la clave que envió el webhook. Comprueba que los secretos de prueba y real no estén intercambiados.
Si 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.
Si el webhook responde Ignored: el webhook procede de un Merchant ID distinto al de los ajustes de ese modo. Comprueba Test Merchant ID (PSPID) o Live Merchant ID (PSPID).
Si el webhook responde Retry later: el pedido se estaba confirmando con otra solicitud en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Worldline reintenta el webhook. Consulta el campo Log para ver el motivo.
La URL del webhook muestra Method not allowed en el navegador: es normal. La URL solo acepta solicitudes de Worldline.
Si Test credentials o Live credentials muestra un error: guarda primero los ajustes y luego comprueba que el Merchant ID, el API Key ID y el Secret API Key procedan de la misma cuenta, y que los valores de prueba estén en los campos de prueba y los reales en los campos reales.
El cliente ve un error al elegir Worldline: consulta el campo Log de la página del módulo. Los errores se registran aunque Logging esté desactivado. Para ver todos los detalles de las solicitudes, activa Logging y vuelve a intentarlo.
Los pagos de prueba no confirman un pago real: las pruebas y el modo real están separados. Cambia Test Mode al modo que quieras y usa las credenciales y el webhook de esa cuenta.
El pedido está en Worldline payment on hold o en Awaiting Worldline capture tras el pago: lee las notas del bloque Worldline payment (véase Estados del pedido). Worldline todavía no ha confirmado la captura (el webhook completa el pedido), o el importe o la moneda pagados eran distintos a los del carrito.
El reembolso falla con un mensaje sobre el entorno: el pago se hizo en el entorno de prueba o en el real, y no están configuradas las credenciales de ese entorno. Introdúcelas e inténtalo de nuevo.
Desarrolladores: el hook actionWlgHostedCheckoutData modifica la solicitud de la página de pago alojada antes de enviarla, por ejemplo para limitar los métodos de pago que se muestran.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Worldline Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete Data está activado, se eliminan los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y los reembolsos de Worldline y los estados de pedido Awaiting Worldline capture y Worldline payment on hold siempre se conservan, para que los pedidos pagados antes puedan seguir reembolsándose tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Worldline es una marca comercial de su respectivo titular. Este módulo no está afiliado a Worldline ni cuenta con su respaldo.