Pular para o conteúdo principal
Versão: 1.x

Gateway Square Terminal

O gateway Square Terminal permite receber pagamentos de pedidos do WooCommerce em dispositivos 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

Pareamento Fácil

Pareie terminais pelo WooCommerce usando um código de dispositivo Square de curta duração

Confirmação via Webhook

Webhooks verificados do Square confirmam a conclusão, com status em tempo real enquanto você aguarda

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 Square notifica seu site com um webhook assinado. O webhook é o sinal definitivo de conclusão; o POS também faz polling para que o status seja atualizado enquanto você aguarda.

Isso significa que o dispositivo Square Terminal deve estar online e conectado à mesma conta e localização do Square, e seu site deve estar acessível publicamente via HTTPS para que o Square possa entregar os webhooks.

Instalaçã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

Configurar as Opções do Square

  1. Navegue até WP Admin > WooCommerce > Configurações > Pagamentos
  2. Encontre Square Terminal na lista de métodos de pagamento e clique para abrir as configurações
  3. Escolha o Ambiente (Sandbox para testes, Production para pagamentos reais)
  4. Insira seu Token de Acesso para o ambiente selecionado (Sandbox ou Production), disponível no Painel de Desenvolvedores Square
  5. Insira seu ID de Localização — a localização Square onde os pagamentos do Terminal são realizados
  6. Insira sua Chave de Assinatura do Webhook e a URL de Notificação do Webhook (consulte a próxima etapa)
  7. Clique em Validar Configurações para confirmar que as credenciais funcionam e salve
nota

Não é necessário ativar o gateway Square Terminal nas configurações do WooCommerce. Ele será ativado especificamente para o POS em uma etapa posterior.

3

Configurar Webhooks no Square

O Square envia um webhook assinado quando um pagamento no Terminal é concluído, e é isso que marca o pedido como pago.

  1. No Painel de Desenvolvedores Square, abra seu aplicativo e acesse a seção Webhooks
  2. Adicione uma assinatura para o evento terminal.checkout.updated
  3. Defina a URL de notificação como a URL de Notificação de Webhook exibida nas configurações do plugin — ela deve corresponder exatamente
  4. Copie a Chave de Assinatura do Webhook nas configurações do plugin para que os eventos recebidos possam ser verificados
Importante

A URL de Notificação de Webhook no Square deve corresponder exatamente ao valor nas configurações do plugin, e a Chave de Assinatura do Webhook deve estar correta. Caso não correspondam, os pagamentos do Square serão concluídos no dispositivo, mas o pedido do WooCommerce não será atualizado.

4

Parear o Square Terminal

  1. Na mesma página de configurações, clique em Criar Código de Dispositivo
  2. Um código de pareamento é gerado e exibido para você
  3. No Square Terminal, faça login e insira o código na tela de pareamento do dispositivo
  4. Após o pareamento, o terminal é vinculado à localização configurada. Anote o ID do Dispositivo — você precisará informá-lo ao realizar um pagamento
Importante

O terminal deve estar pareado com sucesso e online antes de processar pagamentos. Certifique-se de que o pareamento esteja concluído antes de prosseguir.

5

Ativar no WCPOS

  1. Acesse WP Admin > POS > Configurações > Finalização de compra
  2. Encontre o gateway Square Terminal na lista
  3. Ative o gateway para uso no POS
  4. Salve suas configurações

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: Insira o ID do dispositivo Terminal do terminal pareado que deve receber o pagamento
  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 Automática: Quando o webhook verificado do Square confirma o pagamento, o pedido é marcado como pago. O status é atualizado em tempo real enquanto você aguarda.

Controles de Pagamento​

Ao utilizar o gateway Square Terminal, você tem as seguintes opções:

  • Iniciar Pagamento: Envia uma nova solicitação de pagamento para o terminal selecionado
  • Cancelar Pagamento: Cancela um pagamento que está em andamento no terminal
  • Status do Pagamento: Uma área de status em tempo real exibe o estado atual do pagamento
  • Log de Pagamento: Um registro por pedido documenta cada etapa e resultado relevante do Square

Gerenciamento de Pedidos​

  • Conclusão Autoritativa por Webhook: Os pedidos são marcados como pagos somente quando um webhook verificado do Square confirma o pagamento no Terminal
  • 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
Credenciais da API: Access Token, Location ID e Webhook Signature Key do Painel de Desenvolvedor Square
Hardware Compatível: Um dispositivo Square Terminal, online e conectado à mesma localização Square
Site HTTPS Público: Seu site deve estar acessível via HTTPS para que o Square possa entregar webhooks
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 da Square: o checkout é criado pelo seu site e enviado ao dispositivo pareado pela Square. O terminal deve estar online e conectado à mesma conta e localização Square, e seu site deve receber webhooks da Square via HTTPS para que os pedidos sejam atualizados.

Terminais Compatíveis​

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

Escopo e Limitações​

Escopo da v0.1
  • Esta versão inicial é focada 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.
  • Este plugin apenas coleta pagamentos — reembolsos ainda não são suportados. Os identificadores da Square são armazenados no pedido para que o suporte a reembolsos possa ser adicionado futuramente.

Solução de Problemas​

Problemas Comuns​

O dispositivo não emparelha
  • Verifique se o Código do Dispositivo foi inserido antes de expirar — gere um novo com Criar Código do Dispositivo se necessário
  • Confirme que o terminal está online e conectado à mesma conta Square e ao mesmo ID de Localização do plugin
  • Verifique se o Ambiente (Sandbox/Produção) e o Token de Acesso correspondem à conta na qual o terminal está conectado
A validação das configurações falha
  • Verifique se o Token de Acesso 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
  • Copie o token novamente no Painel de Desenvolvedor do Square para descartar caracteres indesejados
O pagamento é concluído no terminal, mas o pedido não é atualizado
  • O URL de Notificação de Webhook no Square deve corresponder exatamente à configuração do plugin
  • Verifique se o evento terminal.checkout.updated está inscrito no Painel de Desenvolvedor do Square
  • Confirme que a Chave de Assinatura do Webhook no plugin corresponde à configurada no Square
  • Verifique se o seu site está acessível publicamente via HTTPS; confira as tentativas de entrega de webhook no Painel do Square
O pagamento não inicia
  • Confirme que um ID do dispositivo Terminal válido foi inserido e que o dispositivo está pareado e online
  • Verifique se o dispositivo está conectado ao ID da localização configurado
  • Consulte o Log de pagamentos e os logs de erro do WordPress para verificar mensagens da API do Square

Obtendo ajuda​

Para suporte técnico:

Capturas de tela​

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

  • Configuração de credenciais, webhook e pareamento de dispositivo do Square
  • Ativação do gateway nas configurações do WCPOS
  • Fluxo de processamento de pagamento no checkout do POS