Pasarela Square Terminal
La pasarela Square Terminal permite cobrar pagos de pedidos de WooCommerce en hardware Square Terminal directamente desde WCPOS. El pago se solicita desde WooCommerce y se completa en un dispositivo Square Terminal emparejado; el resultado se registra en el pedido.
Características
Integración de hardware
Envío de pagos a dispositivos Square Terminal emparejados para cobrar pagos con tarjeta presente
Conexión con un clic
Autorice directamente con Square: no hay que crear ni pegar ningún token de acceso
Finalización fiable
Los pagos se confirman mediante sondeo y un barrido en segundo plano, con webhooks para acelerarlo
Transacciones seguras
Procesamiento de pagos con tarjeta presente compatible con PCI, gestionado en hardware de Square
Sandbox y producción
Validar contra el Square Sandbox antes de cambiar a pagos en producción
Cómo funciona
A diferencia de las pasarelas basadas en SDK de navegador, Square Terminal utiliza la API Terminal del lado del servidor de Square. Al iniciar un pago, WooCommerce crea un Terminal Checkout para el pedido y Square lo envía al dispositivo emparejado. El cliente paga en el terminal y el resultado se registra en el pedido.
Cómo se confirma un pago. El POS sondea a Square mientras el pago está en curso, y un barrido en segundo plano concilia todo lo que el sondeo no capte, por ejemplo una pestaña del navegador cerrada. Los webhooks de Square son un añadido opcional que acorta la espera; no son obligatorios, y un sitio sin ellos nunca pierde un pago.
El dispositivo Square Terminal debe estar en línea y con sesión iniciada en la misma cuenta y ubicación de Square que el plugin.
Configuración
Instalar Square Terminal for WooCommerce
Instálelo desde WP Admin > POS > Ajustes > Extensiones, o descargue el zip del plugin más reciente (no el zip ni el tarball del código fuente de GitHub) desde la página de versiones de GitHub y súbalo mediante Plugins > Añadir nuevo > Subir plugin.
Conectar con Square
- Vaya a
WP Admin > WooCommerce > Ajustes > Pagosy abra Square Terminal - En Cuenta de Square, elija el Entorno:
Sandboxpara pruebas,Productionpara pagos reales - Haga clic en Conectar con Square y apruebe los permisos que le muestre Square
- Elija el Location ID: la ubicación de Square para la que el Terminal cobra los pagos
Elija el entorno antes de conectar. Una conexión cubre un único entorno; una conexión de sandbox nunca podrá autorizar pagos de producción.
El entorno y el Location ID se rellenan previamente a partir de sus ajustes. Solo se leen esos dos valores: no se comparten credenciales entre los plugins y sigue siendo necesario conectar o proporcionar aquí un token de acceso.
Abra Ajustes avanzados y pegue un token de acceso para el entorno seleccionado en lugar de conectar. Todo lo demás funciona igual.
Emparejar el Square Terminal
En Terminal:
- Haga clic en Crear código de dispositivo: aparecerá un código de emparejamiento
- En el Square Terminal, abra la pantalla de inicio de sesión con código de dispositivo e introduzca el código. Si el Terminal tiene sesión iniciada en Square POS o en otra integración, cierre esa sesión primero: la pantalla de código de dispositivo no es accesible mientras el terminal está en uso en otro sitio.
- Haga clic en Buscar lectores para confirmar que ahora aparece en Emparejado con este plugin
Que la lista esté vacía antes del emparejamiento es lo esperado, no un fallo. La API de dispositivos de Square solo informa de los Terminals configurados para su uso con la API Terminal: un Terminal que ejecuta Square POS no aparece en absoluto hasta que se introduce en él un código de dispositivo.
Activar en WCPOS
- Vaya a
WP Admin > POS > Ajustes > Pago - Localice la pasarela Square Terminal y actívela para el POS
- Guarde los ajustes
La casilla Activar/Desactivar de la pantalla de ajustes de WooCommerce controla únicamente el pago de la tienda online. WCPOS utiliza esta pasarela automáticamente una vez configurada, esté o no marcada esa casilla.
Emparejar un Terminal
Un Square Terminal debe emparejarse con este plugin antes de que un cajero pueda seleccionarlo. El emparejamiento crea un código de dispositivo de la API Terminal, y esa es la única forma en que el plugin puede dirigirse al dispositivo.
En Terminal, dentro de la pantalla de ajustes:
- Crear código de dispositivo: genera un código para introducir en el Terminal. Es de corta duración; genere uno nuevo si caduca.
- Buscar lectores: enumera lo que Square puede ver, en dos grupos:
- Emparejado con este plugin: seleccionable en el pago
- Otros dispositivos que Square ve en esta ubicación: configurados por otra aplicación, por lo que no son seleccionables aquí hasta emparejarlos con este plugin
- Validar ajustes: comprueba las credenciales y la ubicación contra Square
Los códigos de dispositivo pertenecen a la aplicación que los creó, así que un Terminal configurado por otra integración de la API Terminal aparece en Otros dispositivos que Square ve, pero no se puede seleccionar aquí. Un Terminal que ejecuta Square POS no aparece en absoluto.
En ambos casos la solución es la misma: cierre en el Terminal la sesión de aquello a lo que esté emparejado y luego introduzca un nuevo código de Crear código de dispositivo de aquí.
Webhooks
Los webhooks son opcionales. Acortan el tiempo que tarda en confirmarse un pago. El sondeo y el barrido en segundo plano confirman todos los pagos igualmente, así que un sitio sin suscripción de webhooks sigue funcionando correctamente, solo que tarda un poco más en cerrarse.
Una suscripción de webhook pertenece a una aplicación de Square, y añadir una requiere acceso a esa aplicación en el Square Developer Dashboard. Si ha conectado con Conectar con Square, está autorizando la aplicación de WCPOS en lugar de una propia, por lo que no hay ningún panel en el que añadir una suscripción ni ninguna clave de firma que copiar.
Los pagos se siguen confirmando con normalidad, mediante el sondeo y el barrido. Los pasos siguientes solo se aplican si configuró el plugin con su propio token de acceso en Ajustes avanzados.
Para añadir una, utilizando su propia aplicación de Square:
- En la pantalla de ajustes, en Terminal → Webhooks, haga clic en Copiar para copiar la URL del webhook
- En el Square Developer Dashboard, abra su aplicación y vaya a Webhooks
- Añada una suscripción para el evento
terminal.checkout.updatedy pegue esa URL como URL de notificación - Copie la clave de firma del webhook de Square en Ajustes avanzados del plugin
La fila Webhooks informa entonces de si ha llegado un webhook con firma verificada, y cuándo.
Square firma cada webhook sobre la URL de notificación que se le indicó. Si la URL en Square difiere de la del plugin aunque sea en un carácter, todas las entregas fallan la verificación. Utilice el botón Copiar en lugar de escribirla.
La API de suscripciones de webhooks de Square está limitada al ámbito de la aplicación, no al de cada vendedor, y no se puede llamar con un token de acceso de vendedor. Por eso el plugin no puede crear la suscripción por usted.
Si los webhooks dejan de verificarse
La fila Webhooks muestra Aún no verificado cuando no ha llegado ni se ha verificado ningún webhook con los ajustes actuales. Si ya se han realizado pagos, compruebe en este orden:
- Que la clave de firma del webhook de Ajustes avanzados coincide con la de Square
- Que la URL de notificación de Square coincide exactamente con la URL que muestra el plugin
- Que el evento
terminal.checkout.updatedestá suscrito - Que su sitio es accesible públicamente por HTTPS: consulte los intentos de entrega en el Square Dashboard
Cambiar el entorno, la URL del webhook o la clave de firma restablece esta fila hasta que llegue el siguiente webhook. Es intencionado: una entrega verificada con los ajustes anteriores no dice nada sobre los nuevos.
Referencia de ajustes
La pantalla de ajustes está ordenada tal y como transcurre la configuración.
| Sección | Contiene |
|---|---|
| Cuenta de Square | Entorno, Conectar con Square, Location ID |
| Terminal | Controles de emparejamiento, lista de lectores, estado de los webhooks |
| Comportamiento del pago | Omitir la pantalla de recibo, recoger firma, registros de depuración |
| Ajustes avanzados | Tokens de acceso, clave de firma del webhook, URL de webhook personalizada |
Ajustes avanzados está plegado de forma predeterminada. Contiene los tokens de acceso manuales —necesarios solo si no va a conectar— y la clave de firma del webhook. La URL de webhook personalizada debe quedar vacía salvo que su URL pública difiera de la que deduce el plugin, por ejemplo detrás de un proxy o con un dominio personalizado.
Uso
Procesar pagos
- Añadir artículos: añada productos al carrito en el POS
- Seleccionar la pasarela: elija «Square Terminal» como método de pago
- Elegir dispositivo: seleccione el terminal emparejado en la lista Dispositivo Terminal
- Iniciar el pago: haga clic en Iniciar pago; Square envía el checkout al dispositivo
- Pago del cliente: el cliente acerca, inserta o pasa su tarjeta en el Square Terminal
- Finalización: el estado se actualiza en directo durante la espera y el pedido se marca como pagado en cuanto Square confirma el pago
En Sandbox, la lista de dispositivos contiene los IDs de dispositivo de prueba documentados por Square, de modo que se puede ensayar cualquier resultado —éxito, tiempo de espera agotado, sin conexión— sin hardware.
Controles de pago
- Iniciar pago: envía una nueva solicitud de pago al terminal seleccionado
- Cancelar pago: cancela un pago en curso en el terminal
- Comprobar estado: pregunta a Square el estado actual de inmediato
- Liberar pago: desvincula un terminal que no responde para que el pedido se pueda pagar de otra forma; el checkout abandonado se sigue conciliando en segundo plano
- Registro de pagos: un registro opcional por pedido que anota cada paso y resultado de Square
Gestión de pedidos
- Finalización verificada: los pedidos se marcan como pagados solo después de verificar el pago contra el objeto Payment de Square, nunca a partir de una señal sin verificar
- Seguimiento del pago: los identificadores de Square y un registro de pagos se almacenan en el pedido, y los pasos clave se escriben en las notas del pedido
- Generación de recibos: los recibos estándar del POS se generan tras los pagos correctos
Requisitos
Compatibilidad de hardware
Square Terminal utiliza la API Terminal del lado del servidor de Square: el checkout lo crea su sitio y Square lo entrega al dispositivo emparejado. El terminal debe estar en línea y con sesión iniciada en la misma cuenta y ubicación de Square que el plugin.
Terminales compatibles
- Square Terminal ✅ — el terminal de tarjeta de sobremesa específico de Square
Alcance y limitaciones
- Centrado en los flujos de POS / pago de pedidos. La disponibilidad en el pago de la tienda online orientada al cliente está desactivada de forma predeterminada y debe activarse explícitamente.
- Solo cobra pagos: los reembolsos aún no son compatibles. Los identificadores de Square se almacenan en el pedido para poder añadir soporte de reembolsos más adelante.
- Las suscripciones de webhooks deben añadirse manualmente en Square; consulte Webhooks.
Solución de problemas
Problemas comunes
La lista de dispositivos Terminal está vacía
- El Terminal debe emparejarse primero con este plugin: utilice Crear código de dispositivo e introduzca el código en el dispositivo
- Un Terminal emparejado a través del Square Dashboard o de la aplicación Square POS no aparecerá hasta que se empareje aquí
- Haga clic en Buscar lectores: si aparece en Otros dispositivos que Square ve, existe pero no está emparejado con este plugin
- Confirme que el Location ID coincide con la ubicación en la que el Terminal tiene la sesión iniciada
El dispositivo no se empareja
- Asegúrese de haber introducido el código de dispositivo antes de que caducara: genere uno nuevo con Crear código de dispositivo
- Confirme que el terminal está en línea y con sesión iniciada en la misma cuenta de Square y el mismo Location ID que el plugin
- Compruebe que el Entorno coincide con la cuenta en la que el terminal tiene la sesión iniciada
Validar ajustes falla
- Si está conectado, compruebe que la fila Cuenta de Square sigue mostrando Conectado con Square; si le pide que vuelva a conectar, la autorización ha caducado
- Si utiliza un token de acceso, verifique que coincide con el Entorno seleccionado: un token de Sandbox no funcionará en Production, ni al revés
- Confirme que el Location ID pertenece a esa cuenta
El pago se completa en el terminal, pero el pedido tarda en actualizarse
- Esto es justo lo que resuelven los webhooks. Sin uno, el pedido se actualiza cuando el sondeo o el barrido en segundo plano lo concilian
- Revise la fila Webhooks: si indica Aún no verificado después de haber realizado pagos, siga Si los webhooks dejan de verificarse
- El pedido nunca se pierde: el barrido concilia cualquier pago que el sondeo no capte
El pago no se inicia
- Confirme que hay un terminal seleccionado y que el dispositivo está emparejado y en línea
- Compruebe que el dispositivo tiene la sesión iniciada en el Location ID configurado
- Revise el Registro de pagos y
WooCommerce > Estado > Registrosen busca de mensajes de la API de Square
Indica que hay que volver a conectar con Square
Las autorizaciones de Square se renuevan automáticamente. Si una renovación no puede completarse, el plugin finaliza la autorización en lugar de dejarla en un estado inutilizable, y la pantalla de ajustes le pide que vuelva a conectar. Haga clic en Volver a conectar con Square; no hay que cambiar nada más.
Obtener ayuda
Para soporte técnico:
- Visite el repositorio de GitHub para informar de problemas
- Consulte la documentación de la API Terminal de Square para obtener orientación sobre hardware y API
- Contacte con el soporte de Square para cuestiones de cuenta y hardware
Los registros se escriben en WooCommerce > Estado > Registros bajo el identificador sqtwc, y anotan cada consulta de dispositivo y cada resultado de webhook.
Capturas de pantalla
Se añadirán capturas de pantalla en una actualización futura para mostrar:
- Las secciones Cuenta de Square, Terminal y Ajustes avanzados
- La activación de la pasarela en los ajustes de WCPOS
- El flujo de procesamiento de pagos en el pago del POS