VibeFox Square for OpenCart — Ayuda

Requisitos

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

PHP: 8.0 o posterior.

Moneda: la moneda del pedido 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 se oculta en la finalización de compra. JPY se cobra en yenes enteros.

Cuenta de Square: necesitas una aplicación en el Square Developer Dashboard. Desde ahí copias el Application ID y el Access Token (página Credentials) y el Location ID (página Locations). Los valores de Sandbox y de Production son distintos. No es necesario ningún webhook: la extensión recibe 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

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_square_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_square_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_square_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también 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 Square 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. Deja activado Sandbox Mode e introduce el Application ID, el Access Token y el Location ID del sandbox (ver Configuración). Haz clic en Save: la extensión 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 vuelve a guardar.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_square_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 Square Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Introduce la clave de licencia y las credenciales de Square como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.

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

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Square 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 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), 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. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title no puede estar vacío (hasta 128 caracteres), Sort Order debe ser un número entero (se permiten valores negativos), Total debe ser un número igual o mayor que 0, y la zona geográfica y los estados de pedido indicados deben existir; si no, no se guarda nada. Después, la extensión comprueba las credenciales del modo seleccionado con Square. Los ajustes se guardan en cualquier caso, y los avisos aparecen en un bloque rojo encima de los ajustes: Square rechazó el Access Token, el Location ID no se encontró para este token, no se pudieron comprobar las credenciales o 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: la extensión recuerda la moneda de la ubicación comprobada y oculta el método de pago para los pedidos en cualquier otra moneda. También avisa si se usa un Application ID de sandbox en modo de producción o al revés.

Square

Enable/Disable: Enable Square Payment Gateway activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que ven los clientes en 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: el texto que el cliente ve en el paso Confirm Order, encima del formulario de tarjeta. Predeterminado: Pay securely with your credit or debit card via Square.

Sort Order: la posición del pago con tarjeta entre los métodos de pago de la finalización de compra. Déjalo vacío o introduce un número entero (se permiten valores negativos).

Geo Zone: muestra el formulario de tarjeta 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 para que se ofrezca el método de pago. Déjalo vacío para ofrecerlo con cualquier total.

Cuenta de Square

Abre el Square Developer Dashboard (la sección tiene 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 distintos) 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 producción mientras está desactivado. Ambos conjuntos se quedan guardados.

Sandbox Mode: los pagos van al sandbox de Square y no se cobra dinero real. Usa tarjetas de prueba de Square. Predeterminado: activado. Los reembolsos de un pedido siempre usan el entorno y la ubicación en los que se pagó el pedido.

Sandbox Application ID: tu Application ID de Square del sandbox (empieza por sandbox-sq0idb-).

Sandbox Access Token: tu Access Token de Square del sandbox.

Sandbox Location ID: tu Location ID de Square del 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 Token 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 Access Token guardado, marca Clear the saved value on save debajo del campo y haz clic en Save.

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 Square haya respondido al pago. Cada campo de abajo muestra tus estados de pedido de OpenCart.

Order Status After Payment: Square completó el pago por exactamente el importe y la moneda del pedido. Predeterminado: Processing.

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í.

Refunded Status: se aplica después de reembolsar el pago por completo desde la pestaña del pedido. Predeterminado: Refunded.

Avanzado

Debug log: los errores y las advertencias siempre se registran. Actívalo para registrar también cada solicitud y respuesta, sin datos de tarjeta ni claves, en wc_sqg_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 wc_sqg_debug.old.log.php. Predeterminado: desactivado.

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 los archivos de registro. Los pagos y reembolsos de Square de los pedidos siempre se conservan. Predeterminado: desactivado.

Importar / Exportar

Exportar: Download JSON guarda los ajustes como un archivo JSON. Los Access Token no se exportan.

Importar: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes. Los Access Token guardados se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (de forma predeterminada Credit / debit card). En el paso Confirm Order, el cliente ve Credit / debit card (Square), tu descripción, MODO SANDBOX — no se realizarán cargos reales. mientras el modo sandbox está activado, y el formulario de tarjeta de Square. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la tarjeta se tokeniza en el navegador con verificación del titular (3-D Secure / SCA): el total del pedido, la moneda y la dirección de pago 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. 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. El formulario de tarjeta de Square aparece entonces en el bloque de confirmación de la parte inferior de la página de finalización de compra, encima de Confirm Order.

Después, la extensión cobra el token a través de la API de pagos de Square por el total del pedido en la moneda del pedido, con el número de pedido como referencia, una nota Order # con el número de pedido y el nombre de tu tienda, y el correo electrónico del cliente. El pago se cobra al instante. 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 pedido, la moneda, el número de pedido y la ubicación. Después, el pedido recibe Order Status After Payment de la forma habitual en OpenCart, con los correos del pedido habituales y la actualización del stock, y el cliente ve la página de éxito del pedido de OpenCart con Hemos recibido tu pago con tarjeta. y un enlace View the receipt al recibo de Square. Si el pago no está COMPLETED o algún valor no coincide, el pedido recibe On Hold (Review) Status y la página muestra Hemos recibido tu pago con 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 y OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order, así que la extensión sigue el carrito: un carrito que ya está pagado nunca se vuelve a cobrar, y el cliente va directamente a la página de éxito.

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 aún no hay respuesta, la extensión busca de inmediato el pago de este pedido en Square. Si lo encuentra, el pedido recibe su estado a partir de él. Si no se encuentra ningún pago, el cliente se queda en el paso Confirm Order con No hemos podido obtener una confirmación del proveedor de pagos. Espera un minuto e inténtalo de nuevo; si tu tarjeta ya fue cobrada, el pago se reconocerá y no se te cobrará dos veces. El siguiente intento del mismo carrito busca primero el pago anterior. Si Square tampoco puede responder a la búsqueda, el pedido recibe On Hold (Review) Status sin pago, con una nota que indica que la tarjeta puede haber sido cobrada, y la página de éxito muestra No hemos podido confirmar tu pago con tarjeta en Square. Revisa tu correo electrónico y el extracto de tu tarjeta antes de volver a pagar, o contacta con nosotros.

Cuando el banco rechaza la tarjeta, el pedido se queda sin estado y el cliente permanece en el paso Confirm Order con 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) no es correcto. Revísalo e inténtalo de nuevo. o Tu banco requiere una 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 escribe en el registro.

OpenCart 4 mantiene un solo pedido para la finalización de compra y lo actualiza, así que tras una tarjeta rechazada el cliente paga el mismo pedido otra vez, y tras un pago sin respuesta de Square el siguiente intento de ese pedido busca primero el pago anterior. Si el pedido de la finalización de compra ya tiene un estado (la tienda lo ha pagado o cerrado) y el carrito contiene productos nuevos, el cliente vuelve a la finalización de compra y el carrito nuevo se paga con un pedido nuevo.

La extensión solo acepta pagos con tarjeta, cobrados al instante. No tiene tarjetas guardadas, perfiles de cliente ni suscripciones, ni Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH ni tarjetas regalo de Square, ni pagos solo de autorización, ni webhooks de Square, ni sincronización de productos o inventario con Square. Las disputas se gestionan en el Square Dashboard.

Pedidos y reembolsos

Estados de pedido

Sin estado (pedido incompleto): el cliente todavía no ha pagado, la tarjeta fue rechazada o la respuesta de Square se perdió y no se encontró ningún pago. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status establecido en Missing Orders.

Order Status After Payment (predeterminado Processing): Square confirmó un pago COMPLETED por el total del pedido. Una nota muestra el ID del pago de Square, la marca de la tarjeta con los últimos 4 dígitos y el modo (sandbox o producción).

On Hold (Review) Status (predeterminado Pending): Square respondió con un pago que no es COMPLETED (por ejemplo APPROVED o PENDING), o con otro importe, moneda, referencia o ubicación. La nota El pago de Square necesita revisión muestra el ID del pago, el estado y los importes. Este estado también se usa cuando el pedido cambió durante el pago, y cuando la respuesta de Square se perdió y no se pudo comprobar (en ese caso no se registra ningún pago, y la nota te pide que revises los pagos de la ubicación en el Square Dashboard con el número de pedido como referencia). Comprueba el pago en el Square Dashboard antes de enviar el pedido.

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

Si se realiza un segundo pago para un carrito que ya tiene un pedido pagado, el pedido pagado no se modifica. Una nota te pide que lo revises y reembolses el duplicado en el Square Dashboard.

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

Pestaña VibeFox Square Gateway

En Sales > Orders abre un pedido pagado con Square. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Square Gateway muestra el Payment ID de Square (con un enlace al pago en el Square Dashboard) con una etiqueta Sandbox para los pagos de sandbox, el Status de Square, la marca de la Card y los últimos 4 dígitos, los importes Paid / order / refunded, el Environment / location, el enlace al Square receipt, el formulario de reembolso, el historial de reembolsos y las Square notes del pedido. Los números de tarjeta nunca se guardan. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

En la pestaña VibeFox Square 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 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 modificar la extensión (se configura en System > Users > User Groups). Los reembolsos se hacen por el importe y la moneda que cobró Square, así que, después de una diferencia de importe, puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido. El reembolso se envía al entorno (sandbox o producción) y a la ubicación en la que se hizo 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 al historial de reembolsos y a las notas con el ID del reembolso de Square. Si Square lo rechaza, la pestaña muestra el error y no se registra ningún reembolso. Un reembolso total pone el pedido en Refunded Status sin avisar al cliente y sin devolver productos al stock, igual que un cambio de estado manual. Un reembolso parcial no cambia el estado.

Las devoluciones de productos en Sales > Returns 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 OpenCart.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Square Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Square 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-square 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, Square 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 pedidos pagados siguen pagados 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

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 cliente sea USD, CAD, AUD, JPY, GBP o EUR y que coincida con la moneda de tu ubicación de Square. La página de ajustes muestra un aviso para cada uno de estos problemas. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado.

El formulario de tarjeta no se carga: el cliente ve No se pudo 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 correspondan al modo seleccionado (los ID de sandbox empiezan por sandbox-). Si el cliente hace clic demasiado pronto, se muestra El formulario de tarjeta todavía se está cargando. Espera un momento e inténtalo de nuevo.

El método de pago desapareció después de guardar: la moneda de la ubicación de Square es distinta de la moneda del pedido. Introduce el Location ID de una ubicación de Square en la moneda de tu tienda y guarda de nuevo: el método se vuelve a mostrar después de 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 de la página Locations de la misma aplicación y del mismo modo.

El cliente ve el mensaje «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 = número de pedido). Si el cliente lo vuelve a intentar, la extensión busca primero el pago anterior y lo usa en lugar de cobrar de nuevo.

El cliente ve el mensaje «Hemos recibido tu pago, pero el pedido no se pudo completar automáticamente»: la tarjeta fue cobrada, pero OpenCart no pudo establecer el estado del pedido. Lee el registro y después completa el pedido manualmente o reembolsa el pago en el Square Dashboard.

El cliente ve el mensaje «Este método de pago no está disponible para tu pedido»: la finalización de compra ya no coincide con el pedido, el método de pago se desactivó mientras tanto o la moneda del pedido no se puede cobrar. El cliente recarga la finalización de compra o elige otro método de pago.

El pedido está en el estado de revisión después del pago: lee las notas de la pestaña VibeFox Square Gateway (ver Estados de pedido). Comprueba el pago en el Square Dashboard y después completa el pedido o reembolsa el pago.

No hay formulario de reembolso en la pestaña: la pestaña indica el motivo: ningún pago de Square cobró dinero por este pedido, no hay un ID de pago de Square registrado (en ese caso la pestaña indica la ubicación y el número de pedido que debes buscar en el Square Dashboard), el pago 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 sandbox o de producción, y el Access Token de ese modo no está configurado. Introdúcelo y vuelve a intentarlo.

Otros errores: activa Debug log y mira el campo Log en la página de la extensión.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Square 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. Si Delete data on uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo sandbox, credenciales, registro) y los archivos de registro. Si está desactivado, se conservan para una reinstalación posterior. Los pagos y reembolsos de Square de los pedidos siempre se conservan, así que los pedidos pagados antes se pueden reembolsar después de 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 Square Gateway en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Square es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Square ni cuenta con su respaldo.