VibeFox Square 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.
Moneda de la tienda: la moneda de tu ubicación de Square: USD, CAD, AUD, JPY, GBP o EUR. Para otras monedas, el método de pago se oculta en la finalización de compra. Square admite vendedores en Estados Unidos, Canadá, Australia, Japón, Reino Unido, Irlanda, Francia y España.
Cuenta de Square: necesitas una aplicación en el Square Developer Dashboard. De ella copias el Application ID y el Access Token (página Credentials) y el Location ID (página Locations). Sandbox y Production tienen valores separados. No se necesita webhook: el plugin obtiene el resultado del pago directamente de la respuesta de Square.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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_square_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Payments > Square > 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. Deja activado Sandbox Mode e introduce el Application ID, el Access Token y el Location ID de sandbox (véase Configuración). Guarda: el plugin verifica las credenciales con Square.
6. Activa Enable/Disable y prueba un pago con las tarjetas de prueba de la guía de pruebas de sandbox de Square. Después desmarca Sandbox Mode, introduce las credenciales de producción y vuelve a guardar.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Square. Encima de los campos, la página muestra Square Gateway está actualmente en modo SANDBOX. No se realizarán cargos reales. mientras el modo sandbox está activado. Avisa cuando Square está activado pero falta el Application ID, el Access Token o el Location ID del modo seleccionado (en ese caso el método de pago se oculta en la finalización de compra), y cuando Square no puede procesar la moneda de la tienda. En la lista de métodos de pago, Square muestra una insignia «Test mode» mientras el modo sandbox está activado.
Al guardar, el plugin verifica las credenciales del modo seleccionado con Square. Verás un error si Square rechaza el Access Token, si el Location ID no se encuentra para este token, si no se pudieron verificar las credenciales o si la moneda de la ubicación no coincide con la moneda de la tienda. Square solo puede cobrar en la moneda de la ubicación: el plugin recuerda la moneda de la ubicación verificada y oculta el método de pago en la finalización de compra para cualquier otra moneda, y la página de configuración sigue mostrando el aviso. También avisa si se usa un Application ID de sandbox en modo real o al revés.
General
Enable/Disable: Enable Square Payment Gateway activa o desactiva el método de pago. Por defecto: off.
Title: el título del método de pago que ve el cliente durante la finalización de compra. Por defecto: Credit / debit card.
Description: la descripción del método de pago que ve el cliente durante la finalización de compra. Por defecto: Pay securely with your credit or debit card via Square.
Square account
Abre el Square Developer Dashboard, elige tu aplicación y copia el Application ID y el Access token de la página Credentials (Sandbox y Production tienen valores separados) y el Location ID de la página Locations. La moneda de la ubicación debe coincidir con la moneda de tu tienda. La página muestra solo los campos de credenciales del modo seleccionado: los campos de sandbox mientras Sandbox Mode está activado, y los campos de producción mientras está desactivado.
Sandbox Mode: Enable sandbox (test) mode. Los pagos se envían al sandbox de Square y no se cobra dinero real. Usa tarjetas de prueba de Square. Por defecto: on.
Sandbox Application ID: tu Application ID de Square de sandbox (empieza por sandbox-sq0idb-).
Sandbox Access Token: tu Access Token de Square de sandbox.
Sandbox Location ID: tu Location ID de Square de sandbox.
Live Application ID: tu Application ID de Square de producción (empieza por sq0idp-).
Live Access Token: tu Access Token de Square de producción.
Live Location ID: tu Location ID de Square de producción.
Advanced
Debug log: Log API requests and responses. Los errores siempre se registran. Actívalo para registrar también cada solicitud, sin datos de tarjeta ni claves. Los registros están en WooCommerce > Status > Logs, origen wcp_square_gateway. Por defecto: off.
Delete data on uninstall: Remove all plugin data when the plugin is deleted. Elimina la configuración de la pasarela y los archivos de registro al borrar el plugin. Los datos de pago de los pedidos se conservan. Por defecto: off.
Finalización de compra
El cliente elige el método de pago (por defecto Credit / debit card) e introduce la tarjeta en el formulario de Square que aparece debajo de la descripción. En modo sandbox, la finalización de compra muestra un aviso de sandbox. Cuando el cliente hace clic en Place order, la tarjeta se tokeniza en el navegador con verificación del comprador (3-D Secure / SCA): el importe, la moneda y el contacto de facturación se envían a Square, y el banco del cliente puede pedir una confirmación. Tu servidor recibe solo un token de un solo uso.
A continuación, el plugin cobra el token mediante la API de pagos de Square por el total del pedido en la moneda del pedido, con el ID del pedido como referencia, una nota Order # con el número de pedido y el nombre de tu sitio, y el correo electrónico de facturación. El pago se captura de inmediato. El pedido solo se marca como pagado después de que Square lo confirme: la respuesta de Square debe mostrar un pago COMPLETED por exactamente el total del pedido, la moneda, el ID del pedido y la ubicación. Entonces el cliente pasa a la página de pedido recibido. Si el pago no es COMPLETED o algún valor no coincide, el pedido se pone en espera con una nota y el cliente igualmente pasa a la página de pedido recibido.
Solo se ejecuta un intento de pago por pedido a la vez. Si el cliente hace clic dos veces o paga en dos pestañas, el segundo intento muestra Este pedido ya se está pagando. Espera un momento y revisa tu correo electrónico antes de volver a intentarlo. Las solicitudes son idempotentes: el mismo pedido, token e importe nunca crean un segundo pago.
Si Square no responde (problema de red, tiempo de espera agotado, error del servidor), la solicitud se reintenta una vez con la misma clave de idempotencia. Si sigue sin respuesta, el cliente ve No hemos podido obtener una confirmación del proveedor de pagos. Espera un minuto y vuelve a intentarlo: si tu tarjeta ya fue cargada, el pago se reconocerá y no se te cobrará dos veces. La nota del pedido te pide revisar el Square Dashboard. En el siguiente intento, el plugin busca primero en Square el pago anterior de este pedido y completa el pedido con él, en lugar de volver a cobrar la tarjeta.
Cuando el banco rechaza la tarjeta, el cliente ve un mensaje breve según el código de error de Square, por ejemplo Tu tarjeta ha sido rechazada. Usa otra tarjeta o método de pago., El código de seguridad de la tarjeta (CVV) es incorrecto. Revísalo e inténtalo de nuevo. o Tu banco requiere una verificación adicional (3-D Secure). Introduce de nuevo la tarjeta y completa la verificación. El motivo técnico se guarda en las notas del pedido y en el registro. El cliente puede volver a intentarlo con otra tarjeta, también más tarde desde la página Pay for order.
El método de pago funciona en la finalización de compra clásica, en el bloque Checkout y en la página Pay for order. Es compatible con WooCommerce High-Performance Order Storage (HPOS).
El plugin acepta solo pagos con tarjeta, capturados de inmediato. No admite tarjetas guardadas ni perfiles de cliente, WooCommerce Subscriptions o Pre-Orders, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH ni tarjetas regalo de Square, pagos solo de autorización, webhooks de Square ni sincronización de productos o inventario con Square. Las disputas se gestionan en el Square Dashboard.
Pedidos y reembolsos
Estados del pedido
Pending payment: el pedido se ha creado y aún no se ha pagado, por ejemplo tras una tarjeta rechazada o una respuesta perdida de Square.
Processing: Square confirmó un pago COMPLETED por el total del pedido. Es el estado estándar de WooCommerce tras el pago (los pedidos con solo productos virtuales descargables pasan a Completado). La nota del pedido muestra el ID de pago de Square, la marca de la tarjeta con las últimas 4 cifras y el modo (sandbox o producción). El ID de transacción es el ID de pago de Square y, en la pantalla del pedido, enlaza con el pago en el Square Dashboard.
On hold: Square respondió con un pago que no es COMPLETED, o con un importe, moneda, referencia o ubicación distintos. La nota El pago de Square necesita revisión muestra el ID del pago, el estado y los importes. Verifica la captura, el importe y la moneda en el Square Dashboard antes de enviar el pedido.
El plugin guarda en el pedido el ID de pago de Square, la marca de la tarjeta y las últimas 4 cifras, el entorno y la ubicación. Los números de tarjeta nunca se guardan.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Credit / debit card (el botón muestra tu Title). Se admiten reembolsos totales y parciales. El reembolso se envía al entorno (sandbox o producción) y a la ubicación en la que se realizó el pago, por lo que debe estar configurado el Access Token de ese modo. Las solicitudes de reembolso son idempotentes y se reintentan una vez si Square no responde. Un reembolso que Square acepta (estado PENDING o COMPLETED) se añade a las notas del pedido con el ID de reembolso de Square. Si Square lo rechaza, WooCommerce muestra el error y no se registra ningún reembolso.
Square completa los reembolsos por su parte. Un reembolso que Square rechace más tarde no se notifica a WooCommerce, y los reembolsos realizados en el Square Dashboard no aparecen en WooCommerce.
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 > Square. 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 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, Square no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve Este método de pago no está disponible. Elige otro, por favor. Los gestores de la tienda que han iniciado sesión siguen viendo el método de pago, marcado como (sin licencia: visible solo para administradores), 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 pedidos pagados siguen pagados, 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
Square no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el Application ID, el Access Token y el Location ID del modo actual están rellenados. Comprueba que la moneda de la tienda (o la moneda del pedido en la página Pay for order) es USD, CAD, AUD, JPY, GBP o EUR y que coincide con la moneda de tu ubicación de Square. La página de configuración muestra un aviso para cada uno de estos problemas.
El formulario de tarjeta no carga: el cliente ve No se ha podido cargar el formulario de tarjeta. Vuelve a cargar la página o elige otro método de pago. Comprueba que el Application ID y el Location ID pertenecen al modo seleccionado (los IDs de sandbox empiezan por sandbox-). Si el cliente hace clic demasiado pronto, se muestra El formulario de tarjeta aún se está cargando. Espera un momento e inténtalo de nuevo.
Los pagos se rechazan aunque la tarjeta esté bien: la moneda de la ubicación debe coincidir con la moneda de la tienda. Guarda la configuración para ver el resultado de la comprobación de credenciales; tras una comprobación correcta, el método se oculta para otras monedas.
Square rechazó el Access Token del modo seleccionado: el token pertenece al otro modo o es incorrecto. Cópialo de nuevo desde la página Credentials de tu aplicación y revisa Sandbox Mode.
No se encontró el Location ID para este Access Token: copia el Location ID de la página Locations de la misma aplicación y del mismo modo.
El cliente vio «No hemos podido obtener una confirmación del proveedor de pagos»: Square no respondió. Lee la nota del pedido y revisa los pagos de esta ubicación en el Square Dashboard (referencia = ID del pedido). Si el cliente vuelve a intentarlo, el plugin busca primero el pago anterior y completa el pedido con él, en lugar de volver a cobrar.
El pedido está On hold: lee la nota El pago de Square necesita revisión. El pago no era COMPLETED, o su importe, moneda o ubicación no coincidían con el pedido. Revísalo en el Square Dashboard y después envía el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre el modo: el pago se realizó en modo sandbox o producción, y el Access Token de ese modo no está configurado. Introdúcelo e inténtalo de nuevo.
Otros errores: activa Debug log y revisa WooCommerce > Status > Logs, origen wcp_square_gateway.
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 contactar con el 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. La configuración de la pasarela y los archivos de registro solo se eliminan si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, los ID de pago de Square y los ID de transacción.
Square es una marca comercial de su respectivo titular. Este plugin no está afiliado a Square ni cuenta con su respaldo.