VibeFox Stripe for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Cuenta de Stripe: necesitas las claves secretas de API 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 dominio.

Instalación

El archivo descargado es un único zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_stripe_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_stripe_gateway.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_stripe_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Stripe Gateway y haz clic en Install (el botón verde +). Tu usuario de administración necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de configuración. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, 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.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_stripe_gateway.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Stripe Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Pega la clave de licencia y las claves de Stripe, y configura el webhook, igual que en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL del webhook es distinta (ver Webhook).

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Stripe Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, 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 (entonces los pedidos solo se confirman cuando el cliente vuelve a la tienda después de pagar), y muestra El modo de prueba está activado: no se realizan pagos reales. mientras el modo de prueba esté activado. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title debe tener de 1 a 128 caracteres, Sort Order debe ser un número entero y Total debe ser un número igual o mayor que 0. Si una clave o un secreto no empieza con el prefijo esperado, los ajustes se guardan y encima de ellos se muestra un aviso que indica el campo.

Stripe Checkout

Enable/Disable: Enable Stripe Gateway activa o desactiva el método de pago. Predeterminado: 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. Predeterminado: Stripe. Obligatorio.

Description: el texto que el cliente ve en el paso Confirm Order, encima del botón de confirmación. Predeterminado: Pay securely with your credit or debit card via Stripe.

Sort Order: la posición de Stripe entre los métodos de pago de la finalización de compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece Stripe solo para las direcciones de pago de la zona geográfica seleccionada. Predeterminado: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el total de la finalización de compra, en la moneda predeterminada de la tienda, que un pedido debe alcanzar antes de ofrecer Stripe. Déjalo vacío para ofrecer Stripe con cualquier total.

Claves de API

Copia las claves secretas desde Stripe Dashboard > Developers > API keys (la página tiene un enlace). Las claves de prueba y las de producción son distintas. El modo de prueba usa solo las claves de prueba, y el modo de producción solo las claves de producción.

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. Predeterminado: activado. Desactívalo para aceptar pagos reales. Mientras esté activado, los clientes ven Modo de prueba: no se realiza ningún pago real. en el paso Confirm Order.

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 de producción. 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 de producción.

Las claves y los secretos guardados nunca se vuelven a mostrar. El campo queda vacío y muestra Guardado: déjalo vacío para conservarlo. Escribe un valor nuevo solo si quieres cambiarlo. Para borrar un valor guardado, marca Clear the saved value on save debajo del campo y haz clic en Save.

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 de producción. Usa la URL que aparece en Endpoint URL en esta sección. En OpenCart 3 tiene el aspecto de https://your-store/index.php?route=extension/payment/wcp_stripe_gateway/webhook, y en OpenCart 4, el de https://your-store/index.php?route=extension/wcp_stripe_gateway/payment/wcp_stripe_gateway.webhook. Se construye a partir de la dirección de la tienda de tu instalación de OpenCart. Copia la URL exactamente como la muestran los ajustes.

Selecciona estos eventos para cada endpoint (también aparecen en esta sección):

Después de crear cada endpoint, copia su secreto de firma (whsec_...) desde Stripe y pégalo en Test Webhook Secret o en Live Webhook Secret. Los webhooks sin una firma válida se rechazan. Un evento solo se acepta si está firmado con el secreto del modo en el que se hizo el pago, así que un secreto de prueba nunca confirma un pago real. Sin el webhook, un pedido solo se confirma cuando el cliente vuelve a la tienda después de pagar.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido incompleto). El pedido recibe un estado solo después de que Stripe haya confirmado el pago. Cada campo de abajo muestra tus estados de pedido de OpenCart.

Order Status After Payment: el estado asignado después de un pago correcto. Predeterminado: Processing.

Awaiting Payment Status: un pago diferido: la finalización de compra ya terminó, pero Stripe todavía no ha confirmado el dinero. Predeterminado: Pending.

On Hold (Review) Status: el pago necesita tu revisión (ver Estados de pedido). Predeterminado: Pending, porque OpenCart no tiene un estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Failed Payment Status: un pago diferido falló. Predeterminado: Failed.

Refunded Status: el pago se reembolsó por completo desde la página del pedido. Predeterminado: Refunded.

Avanzado

Logging: escribe las peticiones y los webhooks de Stripe en strg_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web y, al llegar a 5 MB, se traslada a strg_debug.old.log.php. Las claves y los datos de los clientes no se registran. Predeterminado: desactivado. Mientras esté desactivado no se escribe nada, tampoco los errores.

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 la extensión se eliminan los ajustes de la pasarela y el registro. Las transacciones y los reembolsos de Stripe siempre se conservan, así que los pedidos antiguos siguen siendo reembolsables. Predeterminado: desactivado.

Importar / Exportar

Exportar: Download JSON guarda los ajustes en un archivo JSON. Las claves secretas no se exportan.

Importar: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes. Las claves secretas guardadas se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto Stripe). En el paso Confirm Order, el cliente ve tu descripción y la nota Serás redirigido a Stripe para completar el pago de forma segura. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión crea una sesión de Stripe Checkout por el total del pedido en la moneda del pedido 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. En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque del método de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de finalización de compra. El correo electrónico del cliente se pasa a Stripe, y en la página de Stripe el pago aparece como Order # con el número de pedido.

Después de 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. Después, el pedido recibe su estado de la forma habitual en OpenCart, con los correos habituales del pedido y la actualización del stock, y el cliente ve la página de éxito del pedido de OpenCart. En un pago diferido, la página también muestra Tu pago está siendo confirmado por Stripe. Recibirás un correo electrónico en cuanto se confirme. Si Stripe todavía no ha confirmado el pago cuando el cliente vuelve, aparece una página de Confirmación de pago con el mismo texto y un botón Check again; el webhook asigna el estado del 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ó o un pago diferido falló, el mensaje es El pago no se ha completado. Puedes intentarlo de nuevo o elegir otro método de pago. El carrito se conserva. En OpenCart 4 estos mensajes se muestran encima de la página de finalización de compra. Cada nuevo intento (OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order, OpenCart 4 actualiza el pedido de la finalización de compra) cierra las sesiones de Stripe abiertas anteriores del carrito, así que no se puede pagar dos veces. Si una sesión anterior resulta estar ya pagada, se confirma ese pago en lugar de iniciar uno nuevo. Si otro pedido del mismo carrito ya está pagado con Stripe, no se inicia ningún pago nuevo y el cliente ve la página de éxito del pedido. Cualquier cambio en el carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago.

En OpenCart 4 el pedido se mantiene en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se cerró sin pago entretanto (por ejemplo, porque su pago diferido falló o lo cancelaste), el cliente vuelve a la finalización de compra con el mensaje sobre el pago que no se completó, y el siguiente Confirm Order paga un pedido nuevo. Un pedido pagado nunca se muestra como pagado para un carrito distinto.

Si Stripe no puede iniciar el pago, el cliente se queda en el paso Confirm Order con un breve mensaje encima del botón, 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.

El webhook también funciona mientras la tienda está en modo de mantenimiento, porque OpenCart deja pasar las peticiones de las extensiones de pago.

La extensión solo acepta pagos con tarjeta, capturados inmediatamente en la página de Stripe. No tiene tarjetas guardadas, suscripciones ni pagos recurrentes, ni formulario de tarjeta en tu sitio, ni botones de Apple Pay ni de Google Pay en tu web, y no separa autorización y captura.

Pedidos y reembolsos

Estados de pedido

Sin estado (pedido incompleto): el cliente fue enviado a Stripe y no ha pagado, o Stripe todavía no ha confirmado el pago. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status establecido en Missing Orders.

Order Status After Payment (predeterminado Processing): el pago se confirmó. Una nota muestra el pago de Stripe (pi_...), la sesión y cómo se confirmó (webhook o regreso a la tienda).

Awaiting Payment Status (predeterminado Pending): el cliente completó la compra con un método de pago diferido. Cuando Stripe confirma el pago, el pedido pasa a Order Status After Payment; cuando el pago falla, pasa a Failed Payment Status. OpenCart notifica al cliente de estos cambios.

On Hold (Review) Status (predeterminado Pending): Stripe informó de un importe o una moneda distintos del total del pedido, o el pago llegó después de que el pedido se cancelara o cambiara de estado. La nota lo explica. Revisa el pedido y prepáralo o reembolsa el pago.

Refunded Status (predeterminado Refunded): el pago se reembolsó por completo a través de la extensión.

Si llega un segundo pago para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que lo revises y reembolses el duplicado en el Stripe Dashboard. Lo mismo ocurre cuando el pago pertenece a otro pedido de un carrito que ya está pagado: ese pedido se queda sin estado, y la nota se añade al pedido pagado.

Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox Stripe Gateway

En Sales > Orders abre un pedido pagado con Stripe. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Stripe Gateway muestra el ID del pago de Stripe (con un enlace al pago en el Stripe Dashboard) con una etiqueta Test mode para los pagos de prueba, el Checkout Session, el Status del pago, los importes Paid / refunded, el formulario de reembolso, el historial de reembolsos y las Stripe notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

En la pestaña VibeFox Stripe Gateway introduce el Amount (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional), 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 modificar la extensión (se configura en System > Users > User Groups). Los reembolsos se hacen por el importe y la moneda que cobró Stripe, no por el total del pedido. El reembolso se envía en el modo en el que se hizo el pago (prueba o producción), así que la clave secreta de ese modo debe estar configurada. Si Stripe no acepta el reembolso, la pestaña muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial y a las notas con el ID del reembolso de Stripe. Un reembolso total pone el pedido en Refunded Status sin notificar al cliente y sin devolver productos al stock, igual que un cambio de estado manual. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles una vez que Stripe ha confirmado el pago.

Las devoluciones de productos en Sales > Returns 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 no cambia automáticamente. Actualízalo manualmente si hace falta.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Stripe Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Stripe Gateway > Edit, 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 aparecen la línea Product: opencart-payment-stripe y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (se incluyen el inglés y el ruso).

Si la clave no se acepta, el bloque indica el motivo, por ejemplo Clave no encontrada, Esta clave pertenece a otro producto, Límite de dominios alcanzado o La licencia caducó el seguido de una fecha. Después de que cambie la dirección de la tienda, o después de liberar un hueco de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no está disponible, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Quitar la clave de la tienda no libera su hueco de dominio. Libéralo en tu cuenta de vibefox.net.

Sin una clave activa, Stripe no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, el cliente ve Este método de pago no está disponible. Elige otro. Un usuario administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del panel de administración, así que sin una clave activa el método de pago queda oculto para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando, y los reembolsos funcionan.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del panel de administración: 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 hace falta ninguna tarea cron. Al desinstalar la extensión siempre se elimina la clave de licencia y su estado.

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 tenga una clave secreta: Test Secret Key en modo de prueba, Live Secret Key en modo de producción. La página de ajustes muestra un aviso cuando falta la clave. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado.

El pago se realizó, pero el pedido se queda sin estado: el webhook no funciona. En el Stripe Dashboard comprueba que el endpoint existe en el modo que usas (prueba o producción), 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 recibe su estado cuando el cliente vuelve a la tienda después de pagar.

El webhook responde «Secreto de webhook no configurado»: no hay ningún secreto de webhook configurado. Pega el secreto de firma en los ajustes.

El webhook responde «Firma no válida»: 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 hasta 5 minutos después de la hora del servidor. La respuesta también es «Firma no válida» cuando un evento de un pago real está firmado con el secreto de prueba o al revés: comprueba que los secretos de prueba y de producción no estén intercambiados.

El webhook responde «Ocupado, reintentar»: el pedido estaba siendo confirmado por otra petición en ese mismo momento, o no se pudo asignar el estado del pedido. 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 «El valor no parece correcto» al guardar: se pegó 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 después de Confirm Order: activa Logging y mira el campo Log en la página de la extensión. Este método de pago no está disponible. Recarga la página de finalización de compra. significa que la sesión de pago ya no coincide con el pedido, o que el método de pago se desactivó entretanto: el cliente recarga la finalización de compra. Una clave incorrecta da el mensaje de que el método de pago no está configurado correctamente. Un total del 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 reales se mantienen separados. Cambia Test Mode al modo que quieras usar y utiliza las claves y el webhook de ese modo.

Pedido en estado de revisión después del pago: lee las notas de la pestaña VibeFox Stripe Gateway (ver Estados de pedido) y después prepara el pedido o reembolsa el pago.

No hay formulario de reembolso en la pestaña: la pestaña indica el motivo: el pago todavía no está confirmado, está reembolsado por completo, o tu grupo de usuarios no tiene permiso para modificar la extensión.

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.

Para desarrolladores: antes de crear la sesión de Stripe, la extensión lanza el evento de OpenCart strg_checkout_session_params con los parámetros de la sesión y el pedido.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Stripe Gateway. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre elimina los ajustes propios de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados al reinstalar. El evento de OpenCart de la extensión también se elimina (en OpenCart 4, sus eventos y su acción de inicio, que deja pasar el webhook en modo de mantenimiento). Si Delete Data on Uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo de prueba, claves, secretos de webhook, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Las transacciones y los reembolsos de Stripe siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsándose tras una reinstalación. Los pedidos existentes conservan sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalarla, haz clic en Uninstall (el botón naranja −) junto a VibeFox Stripe Gateway en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Stripe es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Stripe.