VibeFox Stripe 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 Stripe: necesitas las claves API secretas de tu cuenta de Stripe y un endpoint de webhook en el Stripe Dashboard (ver Configuración). Solo se usan las claves secretas y los secretos de firma de los webhooks. Las claves publicables (pk_...) no son necesarias, porque Stripe Checkout es una página alojada por Stripe.
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 subida, haz clic en Configure, o busca más adelante VibeFox Stripe 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 Configure, y haz clic en Activate (ver Clave de licencia).
4. Pega tus claves secretas de Stripe, configura el webhook en el Stripe Dashboard y pega sus secretos de firma (ver Configuración).
5. Activa Enable/Disable y haz clic en Save. Prueba un pago en modo de prueba con la tarjeta 4242 4242 4242 4242 y después desactiva Test Mode.
Al instalarse, el módulo crea dos estados de pedido: Awaiting Stripe payment y Stripe payment on hold. PrestaShop activa 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 Stripe 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 modo actual no tiene clave secreta (en ese caso el método de pago se oculta en la finalización de compra) o no tiene secreto de firma del webhook (en ese caso los pedidos se confirman solo cuando el cliente vuelve a la tienda), y muestra El modo de prueba está activado: no se cobra ningún pago real. mientras el modo de prueba esté activado.
Stripe Checkout
Enable/Disable: Enable Stripe Gateway activa o desactiva el método de pago. Default: off.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. Es también el nombre del método de pago guardado en el pedido. Default: Stripe. Obligatorio.
Description: el texto que aparece debajo del método de pago en la finalización de compra. Default: Pay securely with your credit or debit card via Stripe.
Claves API
Copia las claves secretas desde Stripe Dashboard > Developers > API keys. Las claves de prueba y las reales son independientes. El modo de prueba usa solo las claves de prueba y el modo real solo las claves reales. Al guardar, el módulo te avisa si un valor no empieza por el prefijo esperado, por ejemplo cuando se ha pegado una clave publicable en lugar de una clave secreta.
Test Mode: usa las claves de prueba de Stripe. No se cobra dinero real; paga con tarjetas de prueba de Stripe como 4242 4242 4242 4242. Default: on. Desactívalo para cobrar pagos reales. Mientras esté activado, los clientes ven Modo de prueba: no se cobra ningún pago real. debajo del método de pago.
Test Secret Key: la clave secreta del modo de prueba. Empieza por sk_test_ (o rk_test_ para una clave restringida).
Test Webhook Secret: el secreto de firma (whsec_...) del endpoint de webhook creado en modo de prueba.
Live Secret Key: la clave secreta del modo real. Empieza por sk_live_ (o rk_live_ para una clave restringida).
Live Webhook Secret: el secreto de firma (whsec_...) del endpoint de webhook creado en modo real.
Las claves y secretos guardados nunca se vuelven a mostrar. El campo queda vacío y muestra Guardado — deja el campo vacío para conservarlo. Escribe un valor nuevo solo si quieres cambiarlo.
Clear saved secrets: marca una clave o un secreto y haz clic en Save para eliminarlo. Un campo vacío conserva el valor guardado.
Webhook
El webhook avisa a tu tienda de que se ha realizado un pago. En Stripe Dashboard > Developers > Webhooks añade un endpoint en modo de prueba y otro en modo real. Usa la URL mostrada en Endpoint URL en esta sección. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_stripe_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como la muestran los ajustes, porque Stripe no sigue redirecciones.
Selecciona estos eventos para cada endpoint (también aparecen en esta sección):
Tras crear cada endpoint, copia su secreto de firma (whsec_...) desde Stripe y pégalo en Test Webhook Secret o Live Webhook Secret. Los webhooks sin una firma válida se rechazan. Un evento debe estar firmado con el secreto del modo en que se hizo el pago, así que un secreto de prueba nunca confirma un pago real. Sin el webhook, un pedido se crea solo cuando el cliente vuelve a la tienda después de pagar.
Pedidos
Order Status After Payment: el estado del pedido que se asigna tras un pago correcto.
Los pagos diferidos esperan en Awaiting Stripe payment. Las discrepancias de importe o moneda siempre van a Stripe payment on hold.
Avanzado
Logging: escribe las peticiones de Stripe y los webhooks en logs/strg_debug.log.php en la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves y los datos de clientes no se registran. Default: off. Mientras esté desactivado no se escribe nada.
Log: muestra el tamaño y las últimas entradas 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 de la pasarela y el registro. Las transacciones y los reembolsos de Stripe y los estados de pedido del módulo se conservan siempre, para que los pedidos existentes sigan funcionando. Default: off.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto Stripe) y ve la nota Serás redirigido a Stripe para completar el pago de forma segura. Tras confirmar, el módulo crea una sesión de Stripe Checkout por el total del carrito en la moneda del carrito y envía al cliente a la página de pago de Stripe. Allí el cliente paga con tarjeta de crédito o débito. El correo electrónico del cliente se pasa a Stripe, y el pago aparece en la página de Stripe como Cart # seguido del número de carrito. 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 después de que Stripe lo confirme: mediante el webhook firmado o mediante una petición del servidor a Stripe cuando el cliente vuelve. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Tu pago con Stripe se ha recibido. En un pago diferido, la página muestra Tu pago está siendo confirmado por Stripe. Recibirás un correo electrónico en cuanto se confirme. Si más adelante un pago diferido falla, la página muestra Tu pago con Stripe no se ha completado. Ponte en contacto con nosotros sobre este pedido. Si Stripe todavía no ha confirmado el pago cuando el cliente vuelve, una página de Confirmación del pago muestra el mismo texto y un botón Check again; el webhook crea el pedido en cuanto llega.
Si el cliente cancela en la página de Stripe, la sesión de Stripe se cierra y el cliente vuelve a la finalización de compra con El pago se ha cancelado. Puedes intentarlo de nuevo o elegir otro método de pago. Si el pago no se completó, el mensaje es El pago no se ha completado. Puedes intentarlo de nuevo o elegir otro método de pago. El carrito se conserva. Cada nuevo intento cierra la sesión de Stripe anterior, así que el carrito no se puede pagar dos veces. Si la sesión anterior resulta estar ya pagada, se crea el pedido en lugar de un nuevo pago.
Si Stripe no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo El total del pedido está por debajo del importe mínimo que Stripe puede cobrar en esta moneda. Elige otro método de pago. El motivo técnico se escribe en el registro.
Si un cupón del carrito deja de ser válido entre el pago y su confirmación, PrestaShop lo elimina del pedido. El pedido pasa entonces a Stripe payment on hold con una nota, porque el cliente pagó el precio con el descuento.
El webhook funciona mientras la tienda está en modo de mantenimiento y no se bloquea por la restricción de países de tu tienda.
El módulo solo acepta pagos con tarjeta, cobrados de inmediato en la página de Stripe. No tiene tarjetas guardadas, suscripciones ni pagos recurrentes, ni formulario de tarjeta en el sitio, ni botones de Apple Pay ni de Google Pay en tu sitio, ni autorización y captura por separado.
Pedidos y reembolsos
Estados del pedido
Todavía sin pedido: el cliente fue enviado a Stripe y no ha pagado, o Stripe todavía no ha confirmado el pago. Solo existe el carrito.
Payment accepted, Delivered or Stripe payment on hold: el pago se confirmó. El estado sigue el ajuste Order Status After Payment. El pago se registra con el ID de pago de Stripe (pi_...) como ID de transacción, y una nota muestra el pago de Stripe, la sesión y cómo se confirmó (webhook o retorno).
Awaiting Stripe payment: el cliente terminó la finalización de compra con un método de pago diferido. El pedido pasa a un estado de pagado cuando Stripe confirma el pago.
Stripe payment on hold after payment: Stripe informó de un importe o una moneda distintos al total del pedido (por ejemplo, el carrito se cambió después de iniciar el pago), se eliminó un cupón o el pago llegó después de cancelar el pedido. La nota lo explica. Revisa el pedido y complétalo o reembolsa el pago.
Payment error: un pago diferido ha fallado.
Refunded: el pago se reembolsó por completo a través del módulo.
Si llega un segundo pago para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que lo compruebes y reembolses el duplicado en el Stripe Dashboard.
Bloque Stripe payment
La página del pedido muestra un bloque Stripe payment con el ID de pago de Stripe (enlazado al pago en el Stripe Dashboard), la sesión de Checkout, el estado del pago, el importe que cobró Stripe y el importe reembolsado, una insignia Test mode para los pagos de prueba, el historial de reembolsos y las Stripe notes del pedido.
Reembolsos
En el bloque Stripe payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Stripe. Confirma la pregunta ¿Reembolsar este importe a través de Stripe? Esta acción no se puede deshacer. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos. Los reembolsos se hacen en el importe y la moneda que cobró Stripe, así que tras una discrepancia de importe o moneda puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía en el modo en que se hizo el pago (prueba o real), por lo que la clave secreta de ese modo debe estar configurada. Si Stripe 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 Stripe. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles una vez que Stripe ha confirmado el pago.
El módulo no crea facturas rectificativas. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Stripe.
Los reembolsos hechos en el Stripe Dashboard llegan mediante el webhook charge.refunded y se añaden a las notas con el total reembolsado en Stripe. El estado del pedido y las facturas rectificativas no cambian automáticamente. 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 Stripe Gateway es el primero de Modules > Module Manager > VibeFox Stripe 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-stripe 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 el inglés y el 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 de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no está disponible, 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, Stripe 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 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
Stripe no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el modo actual tiene una clave secreta: Test Secret Key en modo de prueba, Live Secret Key en modo real. La página de ajustes muestra un aviso cuando falta la clave. 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 Stripe Dashboard comprueba que el endpoint existe en el modo que usas (prueba o real), que su URL es exactamente la que aparece en Endpoint URL y que los cuatro eventos están seleccionados. Comprueba que el secreto de firma de ese endpoint está en el campo correspondiente (Test Webhook Secret o Live Webhook Secret). El Stripe Dashboard muestra la respuesta de tu tienda para cada webhook. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar.
El webhook responde Webhook secret not configured: no hay ningún secreto de webhook configurado. Pega el secreto de firma en los ajustes.
El webhook responde Invalid signature: el secreto de firma pertenece a otro endpoint o a otro modo, o el reloj del servidor está mal. Las firmas de Stripe se aceptan dentro de 5 minutos de la hora del servidor. La respuesta también es Invalid signature cuando un evento de un pago real se firma con el secreto de prueba o al revés: comprueba que los secretos de prueba y real no estén intercambiados.
El webhook responde Busy, retry: otra petición estaba confirmando el pedido en el mismo momento, o el pedido no se pudo crear (por ejemplo, porque el módulo está desactivado). Stripe reintenta el webhook automáticamente. Activa Logging para ver el motivo.
La URL del webhook muestra Method not allowed en el navegador: es normal. La URL solo acepta peticiones de Stripe.
Aviso de que el valor no parece correcto al guardar: se ha pegado una clave en el campo equivocado. Las claves secretas empiezan por sk_test_ / rk_test_ o sk_live_ / rk_live_, y los secretos de webhook por whsec_.
El cliente ve un error al elegir Stripe: activa Logging y revisa el campo Log de la página del módulo. Una clave incorrecta da el mensaje de que el método de pago no está configurado correctamente. Un total de pedido por debajo del mínimo de Stripe para la moneda (por ejemplo 0.50 EUR) no se puede cobrar con Stripe.
Los pagos de prueba no confirman un pago real: los pagos de prueba y los reales están separados. Cambia Test Mode al modo que quieras usar y utiliza las claves y el webhook de ese modo.
El pedido está en Stripe payment on hold tras el pago: lee las notas del bloque Stripe payment (ver Estados del pedido) y después completa el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o real, y la clave secreta de ese modo no está configurada. Introdúcela y vuelve a intentarlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Stripe Gateway y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete Data on Uninstall está activado, se eliminan los ajustes de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y los reembolsos de Stripe y los estados de pedido Awaiting Stripe payment y Stripe payment on hold se conservan siempre, así que los pedidos pagados antes se pueden reembolsar después de una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Stripe es una marca comercial de su respectivo propietario. Este módulo no está afiliado ni respaldado por Stripe.