Gateway Square Terminal

O gateway Square Terminal permite receber pagamentos de pedidos do WooCommerce em hardware Square Terminal diretamente pelo WCPOS. O pagamento é solicitado pelo WooCommerce e concluído em um dispositivo Square Terminal pareado, e o resultado é registrado no pedido.

Recursos

Integração com Hardware

Envie pagamentos para dispositivos Square Terminal pareados e receba pagamentos com cartão presente

Conexão com um Clique

Autorize diretamente com o Square — sem token de acesso para criar ou colar

Conclusão Confiável

Os pagamentos são confirmados por polling e por uma varredura em segundo plano, com webhooks para acelerar o processo

Transações Seguras

Processamento de pagamentos presenciais com cartão, compatível com PCI, realizado no hardware Square

Sandbox e Produção

Valide no Square Sandbox antes de alternar para pagamentos em produção

Como Funciona

Diferente dos gateways baseados em SDK no navegador, o Square Terminal utiliza a API Terminal server-side do Square. Ao iniciar um pagamento, o WooCommerce cria um Terminal Checkout para o pedido e o Square o envia para o dispositivo pareado. O cliente realiza o pagamento no terminal, e o resultado é registrado no pedido.

Como um pagamento é confirmado. O POS faz polling no Square enquanto o pagamento está em andamento, e uma varredura em segundo plano reconcilia qualquer coisa que o polling deixe passar — uma aba do navegador fechada, por exemplo. Os webhooks do Square são um acréscimo opcional que encurta a espera; eles não são obrigatórios, e um site sem eles nunca perde um pagamento.

O dispositivo Square Terminal deve estar online e conectado à mesma conta e localização do Square configuradas no plugin.

Configuração

1

Instalar o Square Terminal for WooCommerce

Instale a partir de WP Admin > POS > Configurações > Extensões, ou baixe o arquivo zip do plugin mais recente (não o zip ou tarball do código-fonte do GitHub) na página de releases do GitHub e faça o upload via Plugins > Adicionar novo > Enviar plugin.

2

Conectar ao Square

1. Acesse WP Admin > WooCommerce > Configurações > Pagamentos e abra Square Terminal
2. Em Conta Square, escolha o Ambiente — Sandbox para testes, Production para pagamentos reais
3. Clique em Conectar ao Square e aprove as permissões exibidas pelo Square
4. Escolha o ID de Localização — a localização Square para a qual o Terminal recebe pagamentos

Escolha o ambiente antes de conectar. Uma conexão vale para apenas um ambiente; uma conexão sandbox nunca poderá autorizar pagamentos em produção.

Já usa o plugin oficial WooCommerce Square?

O Ambiente e o ID de Localização são pré-preenchidos a partir das configurações dele. Apenas esses dois valores são lidos — nenhuma credencial é compartilhada entre os plugins, e você ainda precisa conectar ou fornecer um token de acesso aqui.

Prefere usar seu próprio token de acesso?

Abra as Configurações avançadas e cole um token de acesso para o ambiente selecionado em vez de conectar. Todo o restante funciona de forma idêntica.

3

Parear seu Square Terminal

Em Terminal:

1. Clique em Criar Código de Dispositivo — um código de pareamento aparece
2. No Square Terminal, abra a tela de login por código de dispositivo e insira o código. Se o Terminal estiver conectado ao Square POS ou a outra integração, saia dela primeiro — a tela de código de dispositivo não fica acessível enquanto ele está em uso em outro lugar.
3. Clique em Verificar leitores para confirmar que ele agora aparece em Pareado com este plugin

Uma lista vazia antes do pareamento é o esperado, não uma falha. A API de dispositivos do Square só informa os Terminals que foram configurados para uso com a API Terminal — um Terminal executando o Square POS não aparece de forma alguma até que um código de dispositivo seja inserido nele.

4

Ativar no WCPOS

1. Acesse WP Admin > POS > Configurações > Finalização de compra
2. Encontre o gateway Square Terminal e ative-o para o POS
3. Salve suas configurações

nota

A caixa Ativar/Desativar na tela de configurações do WooCommerce controla apenas o checkout da loja virtual. O WCPOS usa este gateway automaticamente assim que ele estiver configurado, esteja essa caixa marcada ou não.

Pareando um Terminal

Um Square Terminal precisa estar pareado com este plugin antes que um operador de caixa possa selecioná-lo. O pareamento cria um Código de Dispositivo da API Terminal, e essa é a única forma pela qual o plugin consegue endereçar o dispositivo.

Em Terminal, na tela de configurações:

• Criar Código de Dispositivo — gera um código para inserir no Terminal. Ele é de curta duração; gere um novo se expirar.
• Verificar leitores — lista o que o Square consegue enxergar, em dois grupos:
  • Pareado com este plugin — selecionável no checkout
  • Outros dispositivos que o Square enxerga nesta localização — configurados por outro aplicativo e, portanto, não selecionáveis aqui até serem pareados com este plugin
• Validar Configurações — verifica as credenciais e a localização junto ao Square

Por que um Terminal que você possui pode não ser selecionável

Os Códigos de Dispositivo pertencem ao aplicativo que os criou, então um Terminal configurado por outra integração da API Terminal aparece em Outros dispositivos que o Square enxerga, mas não pode ser selecionado aqui. Um Terminal executando o Square POS não aparece de forma alguma.

De todo modo, a solução é a mesma: desconecte o Terminal daquilo a que ele está pareado no momento e insira um novo Criar Código de Dispositivo aqui.

Webhooks

Os webhooks são opcionais. Eles encurtam o tempo que um pagamento leva para ser confirmado. O polling e a varredura em segundo plano confirmam todos os pagamentos de qualquer forma, então um site sem assinatura de webhook continua funcionando corretamente — apenas com uma liquidação um pouco mais lenta.

Não disponível se você usou o Conectar ao Square

Uma assinatura de webhook pertence a um aplicativo do Square, e adicioná-la exige acesso a esse aplicativo no Painel de Desenvolvedores do Square. Se você conectou com o Conectar ao Square, está autorizando o aplicativo do WCPOS em vez de um aplicativo seu, então não há painel em que você possa adicionar uma assinatura nem chave de assinatura para copiar.

Os pagamentos continuam sendo confirmados normalmente — por polling e pela varredura. As etapas abaixo se aplicam apenas se você configurou o plugin com seu próprio token de acesso nas Configurações avançadas.

Para adicionar uma, usando o seu próprio aplicativo Square:

1. Na tela de configurações, em Terminal → Webhooks, clique em Copiar para copiar a URL do webhook
2. No Painel de Desenvolvedores do Square, abra seu aplicativo e vá até Webhooks
3. Adicione uma assinatura para o evento terminal.checkout.updated, colando essa URL como URL de notificação
4. Copie a Chave de Assinatura do Webhook do Square para as Configurações avançadas do plugin

A linha Webhooks passa então a informar se um webhook com assinatura verificada chegou, e quando.

A URL precisa corresponder exatamente

O Square assina cada webhook com base na URL de notificação que recebeu. Se a URL no Square diferir da do plugin em um único caractere, todas as entregas falham na verificação. Use o botão Copiar em vez de digitá-la.

Por que esta etapa é manual

A API de Assinaturas de Webhook do Square tem escopo no aplicativo, e não em vendedores individuais, e não pode ser chamada com um token de acesso de vendedor. Por isso, o plugin não consegue criar a assinatura por você.

Se os webhooks pararem de ser verificados

A linha Webhooks mostra Ainda não verificado quando nenhum webhook chegou e foi verificado com as configurações atuais. Se já houve pagamentos, verifique nesta ordem:

1. A Chave de Assinatura do Webhook nas Configurações avançadas corresponde à do Square
2. A URL de notificação no Square corresponde exatamente à URL exibida no plugin
3. O evento terminal.checkout.updated está assinado
4. Seu site está publicamente acessível via HTTPS — confira as tentativas de entrega no Painel do Square

Alterar o ambiente, a URL do webhook ou a chave de assinatura reinicia essa linha até a chegada do próximo webhook. Isso é intencional: uma entrega verificada com as configurações antigas não diz nada sobre as novas.

Referência de configurações

A tela de configurações segue a mesma ordem da configuração inicial.

Seção	Contém
Conta Square	Ambiente, Conectar ao Square, ID de Localização
Terminal	Controles de pareamento, lista de leitores, status dos webhooks
Comportamento do checkout	Pular a tela de recibo, coletar assinatura, logs de depuração
Configurações avançadas	Tokens de acesso, chave de assinatura do webhook, substituição da URL de webhook

As Configurações avançadas ficam recolhidas por padrão. Elas guardam os tokens de acesso manuais — necessários apenas se você não estiver conectando — e a chave de assinatura do webhook. A Substituição da URL de webhook deve permanecer vazia, a menos que sua URL pública seja diferente daquela que o plugin deduz, por exemplo, atrás de um proxy ou de um domínio personalizado.

Uso

Processando pagamentos

1. Adicionar itens: Adicione produtos ao seu carrinho no POS
2. Selecionar gateway: Escolha "Square Terminal" como método de pagamento
3. Escolher dispositivo: Selecione o terminal pareado na lista Dispositivo Terminal
4. Iniciar pagamento: Clique em Iniciar pagamento — o Square envia o checkout para o dispositivo
5. Pagamento do Cliente: O cliente aproxima, insere ou passa o cartão no Square Terminal
6. Conclusão: O status é atualizado em tempo real enquanto você aguarda, e o pedido é marcado como pago assim que o Square confirma o pagamento

No Sandbox, a lista de dispositivos contém os IDs de dispositivos de teste documentados pelo Square, de modo que todos os resultados — sucesso, tempo esgotado, offline — podem ser exercitados sem hardware.

Controles de Pagamento

• Iniciar Pagamento: Envia uma nova solicitação de pagamento para o terminal selecionado
• Cancelar Pagamento: Cancela um pagamento que está em andamento no terminal
• Verificar Status: Pergunta imediatamente ao Square qual é o estado atual
• Liberar Pagamento: Desvincula um terminal que não responde para que o pedido possa ser pago de outra forma; o checkout abandonado ainda é reconciliado em segundo plano
• Log de Pagamento: Um registro opcional por pedido que documenta cada etapa e resultado do Square

Gerenciamento de Pedidos

• Conclusão verificada: Os pedidos são marcados como pagos somente após o pagamento ser verificado com o objeto Payment do Square — nunca com base em um sinal não verificado
• Rastreamento de Pagamento: Os identificadores do Square e um log de pagamento são armazenados no pedido, e as etapas principais são registradas nas notas do pedido
• Geração de Recibo: Recibos padrão do POS são gerados após pagamentos bem-sucedidos

Requisitos

Conta Square: Conta de vendedor Square ativa

Localização Square: Uma localização Square e o respectivo ID de Localização

Hardware Compatível: Um dispositivo Square Terminal, online e conectado à mesma localização Square

Site HTTPS Público: Necessário apenas se você quiser webhooks; sem eles, os pagamentos são confirmados por polling

WCPOS: Versão Pro necessária para checkout no POS

Compatibilidade de Hardware

Requisitos de Conectividade

O Square Terminal utiliza a API Terminal server-side do Square: o checkout é criado pelo seu site e entregue ao dispositivo pareado pelo Square. O terminal deve estar online e conectado à mesma conta e localização do Square configuradas no plugin.

Terminais Compatíveis

• Square Terminal ✅ — Terminal de cartão dedicado do Square para balcão

Escopo e Limitações

Escopo atual

• Focado nos fluxos de POS / pagamento de pedido. A disponibilidade no checkout da loja virtual voltado ao cliente está desativada por padrão e deve ser habilitada explicitamente.
• Apenas coleta pagamentos — reembolsos ainda não são suportados. Os identificadores do Square são armazenados no pedido para que o suporte a reembolsos possa ser adicionado futuramente.
• As assinaturas de webhook precisam ser adicionadas manualmente no Square; veja Webhooks.

Solução de Problemas

Problemas Comuns

A lista de Dispositivos Terminal está vazia

• O Terminal precisa estar pareado com este plugin primeiro — use Criar Código de Dispositivo e insira o código no dispositivo
• Um Terminal pareado pelo Painel do Square ou pelo aplicativo Square POS não aparecerá até ser pareado aqui
• Clique em Verificar leitores: se ele aparecer em Outros dispositivos que o Square enxerga, ele existe, mas não está pareado com este plugin
• Confirme que o ID de Localização corresponde à localização em que o Terminal está conectado

O dispositivo não emparelha

• Verifique se o Código do Dispositivo foi inserido antes de expirar — gere um novo com Criar Código de Dispositivo
• Confirme que o terminal está online e conectado à mesma conta Square e ao mesmo ID de Localização do plugin
• Verifique se o Ambiente corresponde à conta na qual o terminal está conectado

A validação das configurações falha

• Se estiver conectado, verifique se a linha Conta Square ainda exibe Conectado ao Square; se ela pedir para reconectar, a autorização expirou
• Se estiver usando um token de acesso, verifique se ele corresponde ao Ambiente selecionado — um token de Sandbox não funciona em Produção, e vice-versa
• Confirme que o ID de Localização pertence a essa conta

O pagamento é concluído no terminal, mas o pedido demora a ser atualizado

• É exatamente isso que os webhooks resolvem. Sem um deles, o pedido é atualizado quando o polling ou a varredura em segundo plano o reconciliar
• Verifique a linha Webhooks — se ela indicar Ainda não verificado depois de já ter havido pagamentos, siga Se os webhooks pararem de ser verificados
• O pedido nunca se perde: a varredura reconcilia qualquer pagamento que o polling deixe passar

O pagamento não inicia

• Confirme que um terminal está selecionado e que o dispositivo está pareado e online
• Verifique se o dispositivo está conectado ao ID de Localização configurado
• Consulte o Log de Pagamento e WooCommerce > Status > Logs para ver mensagens da API do Square

Aparece a mensagem de que é necessário reconectar ao Square

As autorizações do Square são renovadas automaticamente. Se uma renovação não puder ser concluída, o plugin encerra a autorização em vez de deixá-la em um estado inutilizável, e a tela de configurações pede que você reconecte. Clique em Reconectar ao Square — nada mais precisa ser alterado.

Obtendo ajuda

Para suporte técnico:

• Acesse o repositório no GitHub para relatar problemas
• Consulte a documentação da API do Square Terminal para orientações sobre hardware e API
• Entre em contato com o suporte do Square para questões de conta e hardware

Os logs são gravados em WooCommerce > Status > Logs sob o identificador sqtwc e registram cada consulta de dispositivo e cada resultado de webhook.

Capturas de tela

Capturas de tela serão adicionadas em uma atualização futura para mostrar:

• As seções Conta Square, Terminal e Configurações avançadas
• Ativação do gateway nas configurações do WCPOS
• Fluxo de processamento de pagamento no checkout do POS