# Gateway Mollie Terminal O gateway Mollie Terminal permite aceitar pagamentos presenciais em equipamentos [Mollie Terminal](https://www.mollie.com/products/point-of-sale) diretamente no WCPOS. Um pagamento é iniciado no WooCommerce e concluído no terminal, e a confirmação da Mollie é registrada no pedido. ## Recursos[​](#features "Link direto para Recursos") #### Integração de hardware Envie pagamentos para terminais Mollie registrados na conta Mollie e receba pagamentos presenciais com cartão #### Sem emparelhamento manual Os terminais são obtidos em tempo real da conta Mollie — selecione um em uma lista suspensa, sem precisar colar o ID do dispositivo #### Conclusão confiável Os pagamentos são confirmados por consulta à Mollie, e o POS redireciona automaticamente para o recibo assim que o terminal confirma #### Transações seguras Processamento presencial de cartões em conformidade com PCI, realizado no hardware da Mollie #### Suporte a reembolsos Reembolse pela tela do pedido do WooCommerce, com reconciliação com a Mollie para que os reembolsos nunca sejam duplicados ## Como funciona[​](#how-it-works "Link direto para Como funciona") O Mollie Terminal usa os **pagamentos `pointofsale` no lado do servidor da Mollie**. Ao iniciar um pagamento, o WooCommerce cria um pagamento Mollie para o pedido, e a Mollie o envia ao terminal selecionado. O cliente paga no dispositivo, e a **Mollie é a fonte de verdade** para o status do pagamento e do reembolso — os metadados locais do pedido do WooCommerce são apenas um cache. **Como um pagamento é confirmado.** Enquanto o pagamento está em andamento, o POS consulta a Mollie (a cada 2 segundos por padrão) e, quando o terminal confirma, redireciona diretamente para a página de agradecimento. Os webhooks da Mollie também são usados para acelerar esse processo — e a URL do webhook é definida automaticamente em cada pagamento, portanto não há **nada a configurar no painel da Mollie**. O terminal deve estar registrado e ativo na mesma conta da Mollie que o plugin. ## Configuração[​](#setup "Link direto para Configuração") 1 #### Instale o Mollie Terminal for WooCommerce Instale em `WP Admin > POS > Configurações > Extensões` ou baixe o arquivo ZIP mais recente do **plugin** (não o ZIP ou tarball do código-fonte do GitHub) na [página de releases do GitHub](https://github.com/wcpos/mollie-terminal-for-woocommerce/releases) e envie-o por `Plugins > Adicionar novo > Enviar plugin`. 2 #### Configure suas credenciais da Mollie 1. Acesse `WP Admin > WooCommerce > Configurações > Pagamentos` e abra **Mollie Terminal** 2. Defina **Modo** como `Test` para um pagamento simulado no terminal de teste ou como `Live` para um terminal real 3. Defina **Origem da chave de API** para reutilizar a chave do plugin oficial da Mollie ou usar a chave inserida nesta tela 4. Se a chave for inserida aqui, cole a chave de API de teste ou ativa correspondente ao modo selecionado em **Chave de API Mollie** 5. Salvar Teste antes de entrar em produção A Mollie fornece um terminal simulado para pagamentos de teste `pointofsale`. Use o modo `Live` somente quando estiver tudo pronto para enviar pagamentos a um terminal físico ou iOS/Android. Consulte [Escopo e limitações](#scope-and-limitations) para ver o fluxo de teste atual. Não é necessário ID de perfil Os pagamentos `pointofsale` não exigem um **ID de perfil** da Mollie, e os terminais são listados em toda a conta, portanto não há mais nada a colar. 3 #### Escolha seus terminais 1. Selecione um **Terminal padrão** no menu suspenso. A lista é obtida do ambiente Mollie selecionado — os terminais inativos ficam ocultos, pois a Mollie não pode reativá-los. 2. *(Opcional)* Restrinja os **Terminais ativados** aos dispositivos realmente em uso. O terminal padrão salvo continua disponível mesmo que não esteja selecionado aqui; deixe a configuração vazia para permitir todos os terminais ativos. Para desativar um terminal, também altere ou limpe o **Terminal padrão**. 3. *(Opcional)* Ative **Bloquear seleção de terminal** para que os operadores de caixa não possam alterar o terminal na finalização de compra — o terminal padrão será sempre usado, e isso também é aplicado no servidor. 4. Salvar 4 #### Ativar no WCPOS 1. Acesse `WP Admin > POS > Configurações > Finalização de compra` 2. Localize o método de pagamento **Mollie Terminal** e ative-o para o POS 3. Salve as configurações nota A caixa de seleção **Ativar/Desativar** na tela de configurações do WooCommerce controla apenas a finalização de compra da *loja virtual*. O WCPOS usa esse método de pagamento depois de configurado, independentemente de essa caixa estar marcada. ## Referência de configurações[​](#settings "Link direto para Referência de configurações") | Configuração | O que faz | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Ativar/desativar** | Ativa o gateway para o checkout da loja online (não é necessário para o POS) | | **Título** / **Descrição** | Rótulo e texto exibidos ao cliente no checkout | | **Modo** | `Test` usa o terminal de teste simulado da Mollie; `Live` envia pagamentos para um terminal real | | **Origem da chave de API** | Usa a chave inserida abaixo ou reutiliza a chave de teste/produção correspondente do plugin oficial Mollie Payments for WooCommerce. Se a chave compartilhada não estiver disponível, o plugin usará a chave abaixo como alternativa | | **Chave de API da Mollie** | A chave de API de teste ou produção para o modo selecionado. Usada quando **Origem da chave de API** está definida como a chave inserida aqui e como alternativa para uma chave compartilhada ausente | | **Terminal padrão** | O terminal usado por padrão no checkout, escolhido em uma lista suspensa de terminais ativos no ambiente Mollie selecionado | | **Terminais ativados** | Restringe a lista do checkout aos terminais selecionados. Vazio = todos os terminais ativos. O padrão salvo está sempre disponível; portanto, altere-o ou limpe-o também ao retirar um terminal de uso | | **Bloquear seleção de terminal** | Força o terminal padrão no checkout para que os operadores de caixa não possam alterá-lo (requer um terminal padrão) | | **Logs de depuração do checkout** | Mostra as ferramentas **Mostrar logs**, **Copiar** e **Limpar** no painel de pagamento do checkout. Mantenha esta opção desativada, exceto ao coletar logs para o suporte; a atividade de pagamento é sempre registrada em `WooCommerce > Status > Logs` | A URL do webhook é aplicada automaticamente a cada pagamento, portanto, não há campo de webhook a preencher nem configuração necessária no painel da Mollie. ## Uso[​](#usage "Link direto para Uso") ### Processamento de pagamentos[​](#processing-payments "Link direto para Processamento de pagamentos") 1. **Adicionar itens**: Adicione produtos ao carrinho no POS 2. **Selecionar forma de pagamento**: Escolha "Mollie Terminal" como forma de pagamento 3. **Escolher terminal**: Selecione um terminal na lista suspensa (o padrão é o terminal configurado; fica oculto se a seleção de terminal estiver bloqueada) 4. **Iniciar pagamento**: Clique em **Iniciar pagamento no terminal** — a Mollie envia a solicitação de pagamento ao dispositivo 5. **Pagamento do cliente**: O cliente aproxima, insere ou passa o cartão no terminal. O status é atualizado em tempo real — `Sending to terminal…` → `Waiting for terminal…` 6. **Conclusão automática**: Quando o terminal confirma, o pedido é marcado como pago e o POS redireciona automaticamente para o recibo ### Controles de pagamento[​](#payment-controls "Link direto para Controles de pagamento") * **Iniciar pagamento no terminal**: Envie uma nova solicitação de pagamento ao terminal selecionado * **Cancelar pagamento**: Cancele um pagamento que ainda está em aberto. Quando o pagamento chega ao terminal, a Mollie informa que ele não pode mais ser cancelado, e o caixa faz o cancelamento no próprio dispositivo ### Gerenciamento de pedidos[​](#order-management "Link direto para Gerenciamento de pedidos") * **Conclusão verificada**: Cada webhook, consulta, cancelamento e nova tentativa busca o estado autoritativo da Mollie antes de alterar um pedido, portanto os pedidos são marcados como pagos somente com base em um estado confirmado pela Mollie * **Acompanhamento de pagamentos**: As tentativas de pagamento são registradas como histórico somente de acréscimo no pedido * **Geração de recibos**: Recibos padrão do POS são gerados após pagamentos bem-sucedidos ## Reembolsos[​](#refunds "Link direto para Reembolsos") Há suporte para reembolsos. Reembolse um pedido na tela normal de pedidos do WooCommerce, e o reembolso será enviado à Mollie. Como a Mollie é a fonte de referência, as novas tentativas de reembolso são conciliadas com os IDs e os metadados de reembolso da Mollie **antes** de criar outro reembolso, para que um reembolso nunca seja emitido acidentalmente duas vezes. ## Limpeza de pagamentos pendentes antigos[​](#stale-payment-cleanup "Link direto para Limpeza de pagamentos pendentes antigos") Um pagamento `pointofsale` da Mollie pode permanecer "aberto" do lado da Mollie se a finalização da compra for abandonada. O plugin cancela automaticamente esses pagamentos em aberto quando: * a consulta automática atinge o tempo limite (5 minutos por padrão) — o cancelamento é enviado em vez de deixar o pagamento pendente * o pedido é concluído com um método de pagamento **diferente** (por exemplo, o cliente paga em dinheiro), ou o pedido é cancelado no WooCommerce * a página de finalização da compra é fechada durante o pagamento — uma tentativa de cancelamento é acionada quando a aba é fechada * uma varredura do WP-Cron é executada a cada 10 minutos e cancela ou regulariza pagamentos que permanecerem abertos após o limite de expiração (10 minutos por padrão), inclusive quando o navegador fecha ou a conexão cai antes de as outras rotinas de limpeza serem executadas Se o pagamento já chegou ao terminal, a Mollie o informa como não cancelável, e o operador o cancela no próprio dispositivo — essas limpezas não têm efeito nesse caso e são seguras. ## Requisitos[​](#requirements "Link direto para Requisitos") Conta Mollie : Conta Mollie ativa com uma chave de API para o modo selecionado Hardware compatível : Um Mollie Terminal ativo para pagamentos reais; o terminal de teste simulado da Mollie para testes Moeda : EUR — os pagamentos no terminal POS estão limitados a EUR por enquanto WCPOS : A versão Pro é necessária para o checkout do POS Conexão estável : Conexão de internet confiável para comunicação com a API ## Escopo e limitações[​](#scope-and-limitations "Link direto para Escopo e limitações") Modo de teste A Mollie oferece suporte a pagamentos de teste `pointofsale` sem um terminal físico. Ative o Ponto de venda em um perfil Mollie para criar o terminal de teste e, em seguida, defina este gateway como `Test`, use a chave de API de teste correspondente e selecione esse terminal. A Mollie retorna uma URL `changePaymentState` para escolher o resultado simulado. O plugin pode criar e consultar o pagamento de teste, mas o painel de checkout não exibe essa URL no momento. Nas ferramentas de desenvolvedor do navegador, localize a resposta de rede `mtfwc_start_payment` e abra `_links.changePaymentState.href` para definir o resultado; depois, deixe o POS consultá-lo e conciliá-lo. Consulte o [guia de testes de ponto de venda da Mollie](https://docs.mollie.com/docs/in-person-payments-testing). Use o modo `Live` para um terminal físico ou iOS/Android. Moeda Os pagamentos pelo terminal POS estão limitados a **EUR** até que seja confirmado um suporte mais amplo a moedas no Mollie Terminal. ## Solução de problemas[​](#troubleshooting "Link direto para Solução de problemas") ### Problemas comuns[​](#common-issues "Link direto para Problemas comuns") Nenhum terminal aparece na lista suspensa * Confirme se o **Modo** e a chave de API em uso pertencem ao mesmo ambiente da Mollie * No modo de teste, habilite o Ponto de venda em um perfil da Mollie para que a Mollie crie o terminal de teste simulado * No modo Live, verifique se o terminal está registrado e **ativo** na conta da Mollie; terminais inativos ficam ocultos porque a Mollie não pode reativá-los * Verifique se o site consegue acessar a Mollie — a lista é obtida em tempo real pela API O pagamento não inicia * Confirme que um terminal está selecionado (ou que um **Terminal padrão** está definido quando a seleção está bloqueada) * Verifique se o terminal está ligado, online e ativo na mesma conta da Mollie * Verifique se a moeda do pedido é **EUR** O terminal atingiu o tempo limite ou o pagamento permaneceu aberto * O plugin tenta cancelar pagamentos abertos automaticamente quando o tempo limite é atingido (5 minutos por padrão) * Se o pagamento já tiver chegado ao terminal e não puder ser cancelado automaticamente, cancele-o no próprio dispositivo * Depois, é possível iniciar um novo pagamento ou aceitar o pagamento de outra forma Pedido concluído no terminal, mas demora para atualizar * O POS consulta a Mollie a cada 2 segundos e redireciona quando o pagamento é confirmado; um webhook geralmente o confirma antes * Como a Mollie é a fonte confiável, o pedido é conciliado com o estado oficial da Mollie — ele não é perdido * Verifique se há mensagens da API da Mollie em `WooCommerce > Status > Logs` ### Como obter ajuda[​](#getting-help "Link direto para Como obter ajuda") Para suporte técnico: * Acesse o [repositório do GitHub](https://github.com/wcpos/mollie-terminal-for-woocommerce) para relatar problemas * Consulte o [guia de configuração do Mollie Terminal](https://docs.mollie.com/docs/setting-up-terminal) e a [API Create Payment da Mollie](https://docs.mollie.com/reference/create-payment) para dúvidas relacionadas à API * Entre em contato com o suporte da Mollie para problemas 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: * A tela de configurações do Mollie Terminal — chave de API, terminal padrão e terminais ativados * Ativação do gateway nas configurações do WCPOS * Fluxo de processamento de pagamentos no checkout do POS