VibeFox Stripe 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.

HTTPS: tu sitio debe usar HTTPS para los pagos reales.

Cuenta de Stripe: necesitas las claves API secretas de tu cuenta de Stripe y un endpoint de webhook en el Stripe Dashboard (consulta 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 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_stripe_gateway a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre la configuración: WooCommerce > Settings > Payments > Stripe > Manage, o haz clic en Settings debajo del nombre del plugin en la página 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. Pega tus claves secretas de Stripe, configura el webhook en el Stripe Dashboard y pega sus secretos de firma (consulta Configuración).

6. Activa Enable/Disable. Prueba un pago en modo de prueba con la tarjeta 4242 4242 4242 4242 y luego desmarca Test Mode.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Stripe. 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 secreto de firma de webhook, y muestra Test mode is on: no real payments are taken. mientras el modo de prueba está activado. En la lista de métodos de pago, Stripe aparece como pendiente de configuración hasta que el modo actual tenga una clave secreta.

General

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

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely with your credit or debit card via Stripe.

API keys

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 plugin 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: Enable 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. Por defecto: activado. Desmárcalo para aceptar pagos reales.

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.

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 que se muestra en esta sección de la configuración. Tiene este aspecto: https://your-site/wc-api/strg_stripe_webhook/. Si tu sitio usa un prefijo de idioma en las URL, copia la URL exactamente como la muestra la configuración, porque Stripe no sigue las redirecciones.

Selecciona estos eventos para cada endpoint:

Tras 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. Sin el webhook, un pedido solo se confirma 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. El estado se asigna de una vez, sin un segundo cambio de estado.

Avanzado

Logging: Enable logging escribe las solicitudes y los webhooks de Stripe en WooCommerce > Status > Logs, origen wcp_stripe_gateway. Las claves y los datos de los clientes no se registran. Por defecto: desactivado.

Delete Data on Uninstall: si está activado, al eliminar el plugin se borran los ajustes de la pasarela, los datos de Stripe guardados en los pedidos y los registros. Por defecto: desactivado.

Finalización de compra

El cliente elige el método de pago (de forma predeterminada Stripe) y realiza el pedido. El plugin 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. El correo de facturación del cliente se pasa a Stripe, y el pago aparece en la página de Stripe como Order # y el número del pedido.

Tras pagar, el cliente vuelve a la página de pedido recibido de tu tienda. El pedido se marca como pagado solo cuando Stripe lo confirma: mediante el webhook firmado o mediante una solicitud del servidor a Stripe cuando el cliente llega a esa página. Si el pago aún no está confirmado, la página muestra Your payment is being confirmed by Stripe. You will receive an e-mail as soon as it is confirmed.

Si el cliente cancela en la página de Stripe, el pedido se cancela de la forma estándar de WooCommerce. Un cliente puede volver a pagar un pedido no pagado, por ejemplo desde la página Pay for order. Cada nuevo intento cierra la sesión de Stripe anterior, así que el pedido no se puede pagar dos veces.

Si Stripe no puede iniciar el pago, el cliente ve un mensaje breve, por ejemplo que el total del pedido está por debajo del importe mínimo que Stripe puede cobrar en esta moneda, y puede elegir otro método de pago. El motivo técnico se añade a las notas del pedido y al registro. Los gestores de la tienda que han iniciado sesión también lo ven en el mensaje.

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 el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).

El plugin acepta solo 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 o de Google Pay en tu sitio, ni autorización y captura por separado.

Pedidos y reembolsos

Estados del pedido

Pending payment: el cliente fue enviado a Stripe y aún no ha pagado, o Stripe aún no ha confirmado el pago.

Processing, Completed or On Hold: el pago fue confirmado. El estado sigue a Order Status After Payment. La nota del pedido muestra el pago de Stripe y cómo se confirmó (webhook o retorno). El ID de transacción es el ID de pago de Stripe (pi_...), y en la pantalla del pedido enlaza con el pago en el Stripe Dashboard.

On hold after payment: Stripe informó de un importe o una moneda distintos del total del pedido (por ejemplo, el pedido se editó después de iniciar el pago), o el pago llegó después de que el pedido se hubiera cancelado. La nota del pedido lo explica. Revisa el pedido y tramítalo, o reembolsa el pago.

Failed: un pago diferido falló.

Cancelled: el cliente canceló en la página de Stripe, o el pedido fue cancelado por ti o por el tiempo de espera de retención de stock de WooCommerce. La sesión de Stripe abierta del pedido se cierra, así que ya no se puede pagar.

Si llega un segundo pago para un pedido que ya está pagado, el pedido no se vuelve a modificar. Una nota te pide que lo revises y que reembolses el duplicado en el Stripe Dashboard.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Stripe. Se admiten reembolsos totales y parciales. El reembolso se envía en el modo en que se realizó el pago (prueba o real), por lo que debe estar configurada la clave secreta de ese modo. Si Stripe no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con el ID de reembolso de Stripe.

Los reembolsos hechos en el Stripe Dashboard llegan mediante el webhook charge.refunded y se añaden a las notas del pedido. No se registran automáticamente como reembolsos de WooCommerce. Si hace falta, crea un reembolso manual en WooCommerce sin usar Refund via Stripe.

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 > Stripe. 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. 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. Los gestores de la tienda que han iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose 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

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 real. La página de configuración muestra un aviso cuando falta la clave.

El pago se realizó, pero el pedido sigue en Pending payment: 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 muestra la configuración y que están seleccionados los cuatro eventos. 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 confirma cuando el cliente vuelve a la tienda después de pagar.

El webhook responde Webhook secret not configured: no hay configurado ningún secreto de webhook. Pega el secreto de firma en la configuración.

El webhook responde Invalid signature: el secreto de firma pertenece a otro endpoint u otro modo, o el reloj del servidor está mal. Las firmas de Stripe se aceptan con un margen de 5 minutos respecto a la hora del servidor.

El webhook responde Busy, retry: otra solicitud estaba confirmando el pedido en ese mismo momento. Stripe vuelve a intentar el webhook automáticamente.

Aviso al guardar: el valor no parece correcto: 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 al realizar el pedido: abre las notas del pedido o activa Logging y revisa WooCommerce > Status > Logs, origen wcp_stripe_gateway. Una clave incorrecta o ausente 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 pagar con Stripe.

Los pagos de prueba no confirman un pedido real: los pagos de prueba y los reales se mantienen separados. Un pago de prueba nunca confirma un pedido real, y viceversa. Cambia Test Mode al modo que quieras y usa las claves y el webhook de ese modo.

El pedido está On hold after payment: lee la nota del pedido. El importe o la moneda pagados no coincidían con el pedido, o el pago llegó después de que el pedido se cancelara. Tramita el pedido o reembolsa el pago.

El reembolso falla con un mensaje sobre el modo: el pago se realizó en modo de prueba o real, y la clave secreta de ese modo no está configurada. Introdúcela y vuelve a intentarlo.

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 licencia de este plugin siempre se eliminan. Los ajustes de la pasarela, los datos de Stripe guardados en los pedidos y los registros se eliminan solo si Delete Data on Uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Stripe es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Stripe ni cuenta con su respaldo.