VibeFox Square for PrestaShop — Ayuda
Requisitos
PrestaShop: de 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Moneda: la moneda del carrito debe ser la moneda de tu ubicación de Square: USD, CAD, AUD, JPY, GBP o EUR. Para otras monedas, el método de pago no aparece 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 ahí 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 hace falta ningún webhook: el módulo 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 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 VibeFox Square Gateway más tarde 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. Mantén Sandbox Mode activado e introduce el Application ID, el Access Token y el Location ID de sandbox (ver Configuración). Haz clic en Save: el módulo comprueba las credenciales con Square.
5. Activa Enable/Disable, guarda y prueba un pago con las tarjetas de prueba de la guía de pruebas del sandbox de Square. Después desactiva Sandbox Mode, introduce las credenciales de producción y guarda de nuevo.
Al instalarse, el módulo crea el estado de pedido Square payment on hold. PrestaShop asigna un nuevo módulo de pago a las monedas, los países activos en el momento de la instalación y los grupos de clientes. Revísalos, y marca los países que añadas más tarde, en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Square Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra Square Gateway está actualmente en modo SANDBOX. No se realizará ningún cargo real. 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 no aparece en la finalización de compra), cuando Square no puede procesar la moneda predeterminada de tu tienda y cuando la moneda de tu ubicación de Square es distinta de ella.
Al guardar, el módulo comprueba las credenciales del modo seleccionado con Square. Los ajustes se guardan en cualquier caso. Verás un aviso si Square rechaza el Access Token, si no se encuentra el Location ID para este token, si no se pudieron comprobar las credenciales o si la moneda de la ubicación es distinta de la moneda de la tienda. Square solo puede cobrar en la moneda de la ubicación: el módulo recuerda la moneda de la ubicación comprobada y oculta el método de pago para los carritos en cualquier otra moneda. También avisa si se usa un Application ID de sandbox en modo live, o al revés.
Square
Enable/Disable: Enable Square Payment Gateway activa o desactiva el método de pago. Predeterminado: off.
Title: el título del método de pago que ve el cliente durante la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Credit / debit card. Obligatorio.
Description: la descripción del método de pago que ve el cliente durante la finalización de compra. Predeterminado: Pay securely with your credit or debit card via Square. En modo sandbox se añade (SANDBOX MODE).
Cuenta de Square
Abre el Square Developer Dashboard (la sección incluye un enlace), 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 de live mientras no lo esté. Ambos conjuntos permanecen guardados.
Sandbox Mode: los pagos van al sandbox de Square y no se cobra dinero real. Usa tarjetas de prueba de Square. Predeterminado: on.
Sandbox Application ID: tu Application ID de Square para sandbox (empieza por sandbox-sq0idb-).
Sandbox Access Token: tu Access Token de Square para sandbox.
Sandbox Location ID: tu Location ID de Square para 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.
Los access tokens 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.
Clear saved secrets: marca un access token y haz clic en Save para eliminarlo. Un campo vacío conserva el valor guardado.
Avanzado
Debug log: los errores y avisos siempre se registran. Actívalo para registrar también cada solicitud y respuesta, sin datos de tarjeta ni claves, en logs/wc_sqg_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Predeterminado: off.
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 los archivos de registro. Los pagos y reembolsos de Square de los pedidos y el estado de pedido Square payment on hold siempre se conservan. Predeterminado: off.
Finalización de compra
En el paso de pago, 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. Cuando el cliente confirma el pedido, la tarjeta se tokeniza en el navegador con verificación del comprador (3-D Secure / SCA): el total del carrito, la moneda y la dirección de facturación se envían a Square, y el banco del cliente puede pedir una confirmación. Tu tienda recibe solo un token de un solo uso.
Después, el módulo cobra el token mediante la API de pagos de Square por el total del carrito en la moneda del carrito, con el ID del carrito como referencia, una nota Cart # con el número de carrito y el nombre de tu tienda, y el correo electrónico del cliente. El pago se captura de inmediato. El pedido se marca como pagado solo después de que Square lo confirme: la respuesta de Square debe mostrar un pago COMPLETED por exactamente el total del carrito, la moneda, el ID del carrito y la ubicación. Entonces el pedido se crea con Payment accepted, y el cliente ve la página estándar de confirmación del pedido con Hemos recibido el pago con tu tarjeta. y un enlace al recibo de Square. Si el pago no es COMPLETED o algún valor no coincide, el pedido se crea en Square payment on hold y la página muestra Hemos recibido el pago con tu tarjeta y se está revisando. Actualizaremos tu pedido en cuanto termine la revisión.
Solo se ejecuta un intento de pago por carrito a la vez. Si el cliente hace clic dos veces o paga en dos pestañas, el segundo intento ve 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 carrito, el mismo token de tarjeta y el mismo importe nunca crean un segundo pago, y un carrito que ya tiene un pedido nunca se vuelve a cobrar.
Si Square no responde (problema de red, tiempo de espera agotado o error del servidor), la solicitud se repite una vez con la misma clave de idempotencia. Si sigue sin respuesta, el módulo busca de inmediato el pago de este carrito en Square. Si lo encuentra, el pedido se crea con él. Si no se encuentra ningún pago, el cliente permanece en la finalización de compra con No hemos podido obtener una confirmación del proveedor de pagos. Espera un minuto e inténtalo de nuevo; si tu tarjeta ya se cobró, el pago se reconocerá y no se te cobrará dos veces. El siguiente intento busca primero el pago anterior. Si tampoco se puede contactar con Square para la búsqueda, el pedido se crea en Square payment on hold sin pago, con una nota que indica que la tarjeta puede haberse cobrado, y la página de confirmación muestra No hemos podido obtener una confirmación de tu pago con tarjeta desde Square. Revisa tu correo electrónico y el extracto de tu tarjeta antes de volver a pagar, o contáctanos.
Cuando el banco rechaza la tarjeta, no se crea ningún pedido y el cliente permanece en la finalización de compra con un breve mensaje según el código de error de Square, por ejemplo Tu tarjeta fue rechazada. Usa otra tarjeta u otro método de pago., El código de seguridad (CVV) de la tarjeta es incorrecto. Revísalo e inténtalo de nuevo. o Tu banco requiere verificación adicional (3-D Secure). Introduce de nuevo tu tarjeta y completa la verificación. El carrito se conserva y el cliente puede volver a intentarlo con otra tarjeta. El motivo técnico se guarda en el registro.
El módulo solo acepta pagos con tarjeta, capturados de inmediato. No tiene tarjetas guardadas ni perfiles de cliente, suscripciones, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH ni tarjetas regalo de Square, no admite 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
Order statuses
No order yet: la tarjeta fue rechazada, o la respuesta de Square se perdió y no se encontró ningún pago. Solo existe el carrito.
Payment accepted: Square confirmó un pago COMPLETED por el total del carrito. El pago se registra con el ID de pago de Square como ID de transacción, y una nota muestra el ID del pago, la marca de la tarjeta con las últimas 4 cifras y el modo (sandbox o live).
Square payment on hold: Square respondió con un pago que no está COMPLETED (por ejemplo APPROVED), 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. Un pago COMPLETED se registra en el pedido con el importe que Square cobró. Este estado también se usa cuando el carrito cambió durante el pago, y cuando la respuesta de Square se perdió y no pudo comprobarse (en ese caso no se registra ningún pago). Verifica el pago en el Square Dashboard antes de preparar el envío.
Refunded: el pago se reembolsó por completo a través del módulo.
Si llega un segundo pago para un carrito que ya tiene pedido, el pedido no cambia. Una nota te pide que lo compruebes y reembolses el duplicado en el Square Dashboard.
Bloque Square
La página del pedido muestra un bloque Square con el ID del pago de Square (con enlace al pago en el Square Dashboard), el estado de Square, la marca de la tarjeta y las últimas 4 cifras, los importes Paid / order / refunded, el entorno y la ubicación, un enlace al recibo de Square, una insignia Sandbox para los pagos de sandbox, el historial de reembolsos y las Square notes del pedido. Los números de tarjeta nunca se almacenan.
Reembolsos
En el bloque Square introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Square. Confirma la pregunta ¿Reembolsar este importe a través de Square? 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ó Square, así que tras una diferencia de importe puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía al entorno (sandbox o producción) y a la ubicación donde se hizo el pago, por lo que debe estar configurado el Access Token de ese modo. Las solicitudes de reembolso son idempotentes y se repiten una vez si Square no responde. Un reembolso que Square acepta (estado PENDING o COMPLETED) se añade al historial de reembolsos y a las notas con el ID del reembolso de Square. Si Square lo rechaza, el bloque muestra el error y no se registra ningún reembolso. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
El módulo no crea abonos. Los botones estándar de reembolso de PrestaShop en la página del pedido no devuelven dinero a través de Square. Square completa los reembolsos de su lado: un reembolso que Square rechace más tarde no se notifica, y los reembolsos hechos en el Square Dashboard no aparecen en PrestaShop.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Square Gateway es el primero de Modules > Module Manager > VibeFox Square 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-square 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, Square 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 pedidos pagados siguen pagados 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
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 del carrito 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. 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 formulario de tarjeta no carga: el cliente ve No se ha podido cargar el formulario de tarjeta. Recarga la página o elige otro método de pago. Comprueba que el Application ID y el Location ID pertenecen al modo seleccionado (los ID de sandbox empiezan por sandbox-). Si el cliente hace clic demasiado pronto, aparece El formulario de tarjeta aún se está cargando. Espera un momento e inténtalo de nuevo.
El método de pago desapareció tras guardar: la moneda de la ubicación de Square es distinta de la moneda del carrito. Introduce el Location ID de una ubicación de Square en la moneda de tu tienda y guarda de nuevo: el método vuelve a mostrarse tras una comprobación correcta.
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 comprueba Sandbox Mode.
No se encontró el Location ID para este Access Token: copia el Location ID desde 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ó y todavía no se encontró ningún pago. Revisa los pagos de esta ubicación en el Square Dashboard (referencia = ID del carrito). Si el cliente lo vuelve a intentar, el módulo busca primero el pago anterior y crea el pedido con él en lugar de volver a cobrar.
El cliente vio El pago se recibió, pero el pedido no pudo completarse automáticamente: la tarjeta se cobró, pero PrestaShop no pudo crear el pedido (por ejemplo, porque el módulo estaba desactivado en ese momento). Lee el registro y después crea el pedido manualmente o reembolsa el pago en el Square Dashboard.
El pedido está en Square payment on hold: lee las notas del bloque Square (ver Estados del pedido). Revisa el pago en el Square Dashboard y después prepara el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo sandbox o live, y el Access Token de ese modo no está configurado. Introdúcelo e inténtalo de nuevo.
Otros errores: activa Debug log y revisa el campo Log en la página del módulo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Square 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 los archivos de registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los pagos y reembolsos de Square de los pedidos y el estado de pedido Square payment on hold 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, los ID de pago de Square y los ID de transacción.
Square es una marca comercial de su respectivo titular. Este módulo no está afiliado a Square ni cuenta con su respaldo.