# Gateway Square Terminal

O gateway Square Terminal permite receber pagamentos de pedidos do WooCommerce em dispositivos [Square Terminal](https://squareup.com/hardware/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[​](#features "Link direto para 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[​](#how-it-works "Link direto para 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[​](#installation "Link direto para 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](https://github.com/wcpos/square-terminal-for-woocommerce/releases) 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](https://developer.squareup.com/apps)
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](https://developer.squareup.com/apps), 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[​](#usage "Link direto para Uso")

### Processando pagamentos[​](#processing-payments "Link direto para 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[​](#payment-controls "Link direto para 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[​](#order-management "Link direto para 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[​](#requirements "Link direto para 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[​](#hardware-compatibility "Link direto para 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[​](#supported-terminals "Link direto para Terminais Compatíveis")

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

## Escopo e Limitações[​](#scope-and-limitations "Link direto para 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[​](#troubleshooting "Link direto para Solução de Problemas")

### Problemas Comuns[​](#common-issues "Link direto para 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[​](#getting-help "Link direto para Obtendo ajuda")

Para suporte técnico:

* Acesse o [repositório no GitHub](https://github.com/wcpos/square-terminal-for-woocommerce) para relatar problemas
* Consulte a [documentação da API do Square Terminal](https://developer.squareup.com/docs/terminal-api/overview) para orientações sobre hardware e API
* Entre em contato com o suporte do Square para questões de conta e hardware

## Capturas de tela[​](#screenshots "Link direto para 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