VibeFox PayPlug 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.
Moneda e importes: euro (EUR), de 0,99 a 20.000,00 por pago, los valores predeterminados de PayPlug. Con otra moneda del carrito o fuera de estos límites, el método de pago se oculta.
Cuenta de PayPlug: necesitas las claves secretas de tu cuenta de PayPlug: la clave de prueba (sk_test_...) y/o la clave de producción (sk_live_...). No se necesitan otras claves, y no hay que configurar ninguna notificación en PayPlug. Tu tienda debe ser accesible desde internet para recibir notificaciones; si no, los pedidos se crean cuando el cliente vuelve de PayPlug.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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 VibeFox PayPlug Gateway más tarde 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. Pega tus claves secretas del portal de PayPlug (ver Configuración).
5. Activa Enable/Disable y haz clic en Save. Prueba un pago con Test Mode activado y después desactívalo para aceptar pagos reales.
Al instalar, el módulo crea el estado de pedido PayPlug payment on hold. PrestaShop habilita el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox PayPlug 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 cuando el método de pago está activado pero la clave secreta del modo actual está vacía, y cuando la moneda predeterminada de la tienda no es EUR. En ambos casos el método de pago se oculta en la finalización de compra.
Finalización de compra
Enable/Disable: Enable PayPlug Gateway activa o desactiva el método de pago. Predeterminado: off.
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 guardado en el pedido. Predeterminado: PayPlug. Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely by card via PayPlug.
Claves API
Encuentra tus claves secretas en el portal de PayPlug, en Developers > API keys. La sección tiene un enlace al portal.
Test Mode: usa la clave secreta de prueba para los pagos nuevos. No se procesa ningún pago real. Los pagos hechos en el otro modo siguen usando la clave de su propio modo para comprobar el estado y para los reembolsos. Predeterminado: on. Mientras está activado, los clientes ven Test mode: no real payment will be made. debajo del método de pago.
Test Secret Key: tu clave secreta de prueba de PayPlug. Empieza por sk_test_.
Live Secret Key: tu clave secreta de producción de PayPlug. Empieza por sk_live_.
Una clave con el prefijo incorrecto no se guarda. La página muestra, por ejemplo, Test Secret Key must start with "sk_test_". The previous value was kept. Las claves guardadas 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 keys: marca una clave y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Notification URL: la dirección que el módulo envía a PayPlug con cada pago. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_payplug_gateway/webhook. No hay que introducir nada en el portal de PayPlug. La URL debe ser accesible desde internet; si no, los pedidos se crean cuando el cliente vuelve de PayPlug.
Pedidos
Order Status After Payment: el estado del pedido que se asigna tras un pago correcto. El estado se asigna de inmediato, sin un segundo cambio de estado.
Avanzado
Logging: registra las llamadas a la API y las notificaciones en logs/ppg_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. Las claves secretas, los datos de tarjeta y los datos de clientes nunca se registran. Predeterminado: off.
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, los ajustes del módulo y su registro se eliminan al desinstalar el módulo. Los ID de pago de PayPlug guardados en los pedidos y el estado de pedido PayPlug payment on hold se conservan. Predeterminado: off.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto PayPlug, con el logotipo de PayPlug). En modo de prueba la opción muestra Test mode: no real payment will be made. Al confirmar, el módulo crea un pago de PayPlug por el total del carrito en céntimos y envía al cliente a la página de pago de PayPlug. Las direcciones de facturación y de entrega, el correo electrónico y el idioma del carrito se transmiten a PayPlug. Allí el cliente paga con tarjeta. En este punto todavía no existe ningún pedido.
Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando PayPlug lo confirma: el módulo lee el pago desde la API de PayPlug cuando llega la notificación y cuando el cliente vuelve. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your payment with PayPlug has been received. Si el pedido está en espera, la página dice We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Si el pedido está en Payment error o se canceló sin pago, la página dice Your PayPlug payment was not completed. Please contact us about this order. Si no se pudo consultar a PayPlug cuando el cliente vuelve, una página Payment confirmation muestra el mismo texto de "estamos confirmando" y un botón Check again; la notificación crea el pedido en cuanto llega.
Si el cliente cancela en la página de PayPlug, la página de pago se cierra en PayPlug, así que no puede pagarse más tarde por error. El cliente vuelve a la finalización de compra con un mensaje: You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. o, si el pago quedó abierto, Your PayPlug payment was not completed. You can try again or choose another payment method. El carrito se conserva.
Cuando el cliente paga de nuevo el mismo carrito, el módulo primero revisa el intento anterior. Si entretanto se pagó, el pedido se crea sin un nuevo pago. Si sigue abierto por el mismo importe, se usa de nuevo la misma página de pago. Si no, la página anterior se cierra en PayPlug y se crea un pago nuevo.
Si PayPlug no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo PayPlug could not accept your billing details (postcode). Please check them and try again. o The payment provider could not be reached. Please try again in a moment. El motivo técnico se escribe en el registro.
La notificación funciona mientras la tienda está en modo de mantenimiento y no la bloquea la restricción por país de tu tienda.
Los pagos se capturan de inmediato. El módulo no admite pagos a plazos de Oney, tarjetas guardadas de un solo clic, formulario de pago integrado, suscripciones ni captura diferida.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a PayPlug y no ha pagado, o PayPlug todavía no ha confirmado el pago. Solo existe el carrito.
Payment accepted or Delivered: el pago fue confirmado. El estado sigue a Order Status After Payment. El pago se registra con el ID de pago de PayPlug (pay_...) como ID de transacción, y una nota muestra el pago de PayPlug y su modo.
PayPlug payment on hold: el importe pagado o la moneda no coinciden con el carrito (nota amount/currency mismatch, por ejemplo si el carrito se modificó después de iniciar el pago); o se hizo un pago de prueba mientras la tienda estaba en modo de producción, así que no se recibió dinero y no se registra ningún pago; o el pago llegó para un pedido que había sido cancelado; o un pago está autorizado pero no capturado (captúralo en el portal de PayPlug; el pedido se marca como pagado cuando PayPlug lo informa como pagado). La nota explica qué hay que comprobar.
Payment error: un pago autorizado de un pedido en espera falló o se canceló.
Refunded: el pago se reembolsó por completo a través del módulo.
Si un segundo intento de un carrito ya pagado también se paga, el pedido no cambia. Una nota pide que reembolses el pago duplicado en el portal de PayPlug. Un pedido pagado, cancelado o reembolsado nunca se reabre con una notificación posterior.
Bloque de pago de PayPlug
La página del pedido muestra un bloque PayPlug payment con el ID de pago de PayPlug, el estado del pago, el importe pagado y reembolsado, una insignia Test mode para los pagos de prueba, el historial de reembolsos y las PayPlug notes del pedido.
Reembolsos
En el bloque PayPlug payment introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via PayPlug. Confirma la pregunta Refund this amount through PayPlug? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. Los reembolsos se hacen hasta el importe que PayPlug realmente cobró, así que tras una diferencia de importe puedes reembolsar lo que pagó el cliente, no el total del pedido. El reembolso va al pago que realmente pagó el pedido, con la clave secreta del modo (prueba o producción) en el que se hizo, así que esa clave debe estar configurada. Si PayPlug no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas con el ID de reembolso de PayPlug y el motivo. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando PayPlug ha informado de que el pago está pagado.
El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de PayPlug.
Los reembolsos hechos en el portal de PayPlug llegan por notificación y se añaden a las notas una sola vez. No se cuentan en el bloque y no cambian el estado del pedido ni las facturas de abono. Regístralos manualmente si hace falta.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PayPlug Gateway es el primer bloque de Modules > Module Manager > VibeFox PayPlug Gateway > Configure, encima de los ajustes. 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 de ellos están la línea Product: presta-payment-payplug 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 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 dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su hueco de dominio. Libera el hueco en tu cuenta de vibefox.net.
Sin una clave activa, PayPlug 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 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 requieren renovarla. 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 hace falta 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
PayPlug no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el modo actual tiene una clave secreta (Test Secret Key en modo de prueba, Live Secret Key en modo de producción), que la moneda del carrito es EUR y que el total del carrito está entre 0,99 y 20.000,00 EUR. 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. Los desarrolladores pueden cambiar las monedas y los límites con los hooks actionWcpPayplugSupportedCurrencies y actionWcpPayplugAmountLimits (valores en céntimos).
El pago se hizo, pero no se creó ningún pedido: la notificación no llegó a tu tienda y el cliente no volvió. Comprueba que tu tienda es accesible desde internet en la Notification URL que aparece en los ajustes, por ejemplo que ningún cortafuegos ni protección con contraseña la bloquee. Activa Logging y revisa el campo Log para ver las notificaciones rechazadas.
La notificación responde Verification failed.: no se pudo leer el pago desde la API de PayPlug, por ejemplo porque PayPlug no respondió o porque la clave secreta del modo del pago no está configurada. El pedido no cambia y PayPlug vuelve a enviar la notificación.
La notificación responde Temporarily unavailable.: otra petición estaba actualizando el carrito en ese mismo momento, por ejemplo el retorno del cliente, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). PayPlug vuelve a enviar la notificación. El registro muestra el motivo.
La notificación responde Unknown payment. o Payment does not belong to the order.: el pago no lo creó esta tienda o no es para este carrito, por ejemplo un pago de otra tienda en la misma cuenta de PayPlug. Se ignora.
La URL de notificación muestra Method not allowed. en el navegador: es normal. La URL acepta solo peticiones de PayPlug.
El cliente ve un error al elegir PayPlug: activa Logging y revisa el campo Log. Una clave incorrecta da This payment method is temporarily unavailable. Please choose another payment method.; los demás mensajes indican el campo de facturación que PayPlug rechazó.
El pedido está en PayPlug payment on hold tras el pago: lee las notas del bloque PayPlug payment (ver Estados del pedido) y después procesa el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o de producción, y la clave secreta de ese modo no está configurada. Introdúcela y vuelve a intentarlo.
El reembolso falla con Unexpected response from PayPlug.: PayPlug respondió sin un reembolso válido. No se registró nada. Comprueba el reembolso en el portal de PayPlug antes de volver a intentarlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox PayPlug 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 y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de pagos y reembolsos de PayPlug y el estado de pedido PayPlug payment on hold siempre se conservan, así que los pedidos pagados antes pueden reembolsarse después de una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
PayPlug es una marca comercial de su respectivo titular. Este módulo no está afiliado a PayPlug ni cuenta con su respaldo.