VibeFox Comgate for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin se recusa a ser ativado sem ele.
PHP: 8.0 ou superior.
HTTPS: o seu site deve ser acessível pela internet por HTTPS, para que a Comgate possa entregar a notificação em segundo plano.
Moeda: CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK ou SEK. Para outras moedas e para totais abaixo do mínimo da Comgate, o método de pagamento fica oculto. Pagamentos em HUF são arredondados para forints inteiros, como exige a Comgate.
Conta Comgate: você precisa do Merchant ID e do segredo (senha para a comunicação em segundo plano) da conexão da sua loja no portal de clientes da Comgate, e da URL de notificação configurada ali (veja Configuração). A Comgate usa o mesmo Merchant ID e segredo para pagamentos de teste e de produção.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_comgate_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Comgate > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira o Merchant ID e o Secret do portal de clientes da Comgate e configure a URL de notificação ali (veja Configuração).
6. Ative Enable / Disable. Mantenha o Test Mode ativado para um pagamento de teste e, depois, desative-o.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Comgate. Acima dos campos, a página avisa quando a Comgate está ativada, mas faltam o Merchant ID ou o segredo (o método de pagamento fica então oculto na finalização de compra até que os dois sejam preenchidos), e quando a moeda da loja não é suportada. Enquanto o modo de teste estiver ativado, ela mostra Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live.
Geral
Enable / Disable: Enable Comgate Payment Gateway ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: Comgate.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Comgate — cards, bank transfers, wallets and more. No modo de teste, TEST MODE: no real money is charged. é acrescentado a ele, ou exibido sozinho quando a descrição está vazia.
Conexão com a Comgate
Obtenha o identificador da loja (Merchant ID) e a senha (segredo) no portal de clientes da Comgate, em Integration > shop connection settings. No mesmo lugar, defina a URL for passing the payment result (notificação em segundo plano) como a URL exibida nesta seção. Ela tem a forma https://your-site/wc-api/comgate_payment_callback/. A Comgate a chama após cada pagamento; o plugin então verifica o pagamento novamente pela API de status da Comgate antes de alterar o pedido. As URLs de retorno para o cliente são enviadas em cada pagamento. Se o portal também pedir URLs de retorno (pago, cancelado, pendente), use a segunda URL exibida nesta seção, que tem a forma https://your-site/wc-api/comgate_payment_return/?id=${id}&refId=${refId}.
Merchant ID: o identificador de e-shop (merchant) da Comgate.
Secret: a senha para a comunicação em segundo plano (secret) desta conexão da loja.
Test Mode: Create test payments (no money is charged). A Comgate usa o mesmo Merchant ID e segredo para pagamentos de teste e de produção; os pagamentos de teste são marcados com test=true. Os reembolsos são sempre enviados no modo do pagamento original. Padrão: ativado.
Página de pagamento
Payment Methods: quais métodos de pagamento da Comgate o cliente pode escolher. Somente os métodos ativados para a sua loja na Comgate são mostrados.
Language: o idioma da página de pagamento da Comgate. Automatic (site language, English as fallback) (padrão) ou um de 26 idiomas.
Pedidos
Order Status After Payment: o status definido quando a Comgate confirma o pagamento. O status é definido de imediato, sem uma segunda mudança de status.
Avançado
Debug Log: Log API requests and notifications grava em WooCommerce > Status > Logs, origem wcp_comgate_gateway. O segredo e os dados pessoais nunca são registrados. Erros são sempre registrados. Padrão: desativado.
Delete Data on Uninstall: Remove the gateway settings and log files when the plugin is deleted. Os pedidos e os IDs de transação da Comgate neles são sempre mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Comgate) e faz o pedido. O plugin cria o pagamento na Comgate para o total do pedido na moeda do pedido e redireciona o cliente para a página de pagamento da Comgate. O e-mail e o nome de cobrança são enviados à Comgate, e o pagamento é identificado com o número do pedido. É obrigatório um endereço de e-mail de cobrança válido. Na página da Comgate, o cliente paga com um dos métodos que você permitiu.
Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Comgate confirma: o plugin lê o pagamento pela API de status da Comgate, tanto quando a notificação em segundo plano chega quanto quando o cliente volta. Se o pagamento ainda não foi confirmado, por exemplo uma transferência bancária a caminho, a página de pedido recebido mostra Comgate has not confirmed your payment yet. The order will be updated automatically as soon as the payment is confirmed — please do not pay again. Se o pedido foi colocado em espera, a página mostra Your payment is being reviewed. We will contact you if anything else is needed.
Se o pagamento for cancelado ou expirar, o cliente volta à finalização de compra (ou ao carrinho) com The Comgate payment was cancelled or has expired. You can try again or choose another payment method. Um cliente pode pagar novamente um pedido não pago, por exemplo pela página Pay for order. A tentativa anterior é verificada primeiro, então um pagamento que já foi concluído não é cobrado duas vezes, e ela é cancelada na Comgate se ainda estiver aberta. Um pagamento tardio de uma tentativa mais antiga ainda paga um pedido não pago.
Se a Comgate não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, por exemplo The Comgate payment could not be started. Please try again or choose another payment method., que a Comgate não pode aceitar este valor ou moeda, ou que o método de pagamento Comgate escolhido não está disponível. O motivo técnico é gravado no log.
O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).
O plugin aceita pagamentos únicos somente na página da Comgate. Não há pagamentos recorrentes, assinaturas ou cartões salvos, nem checkout Comgate incorporado, nem botões de Apple Pay ou Google Pay no seu site (eles estão disponíveis na página da Comgate), nem captura ou cancelamento de pré-autorizações pelo WooCommerce. Sem a notificação, o status do pagamento não é consultado automaticamente; ele só é verificado quando o cliente volta.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Comgate e ainda não pagou, ou a Comgate informa o pagamento como pendente. A nota do pedido mostra o pagamento criado na Comgate.
Processing or Completed: a Comgate informou o pagamento como PAID, com o mesmo valor e moeda. O status segue Order Status After Payment. O ID da transação do pedido é o ID da transação na Comgate; todas as tentativas são mantidas com o pedido. Pagamentos de teste recebem a nota Comgate test payment — no money was charged.
On hold: o valor ou a moeda pagos diferem do pedido, um pagamento de teste foi confirmado com a loja em modo de produção (nenhum dinheiro foi recebido), ou o pagamento está apenas autorizado (pré-autorização na sua conta Comgate). Um pagamento autorizado se torna pago automaticamente quando você o captura no portal da Comgate. A nota do pedido explica o motivo.
Cancelled: o pagamento atual na Comgate foi cancelado ou expirou. Se a Comgate confirmar o pagamento depois que o WooCommerce cancelou o pedido não pago (por exemplo, uma transferência bancária lenta), o pedido é reaberto como pago, com uma nota para verificar o estoque antes do envio.
Se a Comgate informar outro pagamento PAID para um pedido que já está pago, o pedido não é alterado novamente. Uma nota pede que você verifique no portal da Comgate e reembolse a cobrança duplicada. Uma confirmação reenviada nunca reabre um pedido reembolsado nem um pedido cancelado depois do pagamento.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Comgate (o botão mostra o título do método de pagamento). São compatíveis reembolsos totais e parciais. O reembolso é feito na transação paga da Comgate e enviado no modo (teste ou produção) do pagamento original. A Comgate só reembolsa pagamentos PAID, e no máximo o valor pago; reembolsos em HUF devem ser em forints inteiros. Se a Comgate não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido, com o valor, a transação da Comgate e o motivo.
Reembolsos feitos no portal da Comgate não são informados de volta à loja. Se necessário, crie um reembolso manual no WooCommerce, sem usar o botão Refund via do gateway.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Comgate. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a Comgate não é mostrada aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. Gerentes da loja logados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente automaticamente, em segundo plano.
Solução de problemas
A Comgate não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ativado, se o Merchant ID e o Secret estão preenchidos, se a moeda do pedido é suportada e se o total do pedido não está abaixo do mínimo da Comgate (por exemplo, 1 CZK, 0,10 EUR ou 100 HUF). A página de configurações mostra um aviso quando as credenciais estão ausentes ou a moeda não é suportada.
O pagamento foi feito, mas o pedido continua com o status Pending payment: a Comgate não entregou a notificação em segundo plano. Verifique a URL for passing the payment result no portal da Comgate, se o seu site está acessível pela internet por HTTPS (sem modo de manutenção nem proteção por senha) e o log (ative o Debug Log). A Comgate repete as notificações não entregues; o plugin responde com um erro sempre que não processa uma delas, então ela será reenviada. O pedido também é confirmado quando o cliente volta à loja.
A notificação responde Invalid merchant or secret: o Merchant ID ou o segredo nas configurações não correspondem à conexão da loja no portal da Comgate.
A notificação responde Gateway not configured: o Merchant ID ou o segredo está vazio nas configurações. A Comgate tenta de novo quando eles forem preenchidos.
A notificação responde Order not found, Unknown transaction ou Reference mismatch: a notificação pertence a um pagamento que não foi criado por esta loja para esse pedido. O pedido não é alterado.
A notificação responde Status verification failed, Status verification rejected ou Busy, retry later: a API de status da Comgate não pôde ser acessada, rejeitou a requisição, ou o pedido estava sendo processado por outra requisição no mesmo momento. A Comgate tenta reenviar a notificação.
O cliente vê We could not verify the Comgate payment: o link de retorno não correspondeu ao pedido. Se o dinheiro foi cobrado, a notificação ainda confirma o pedido. Verifique o pagamento no portal da Comgate antes de o cliente pagar novamente.
O cliente vê The order total is below the minimum amount accepted by Comgate ou A valid billing e-mail address is required for Comgate payments: o pedido não pode ser pago com a Comgate do jeito que está.
O pedido está On hold após o pagamento: leia a nota do pedido. O valor ou a moeda pagos eram diferentes, um pagamento de teste chegou em modo de produção, ou o pagamento está apenas autorizado. Verifique o pagamento no portal da Comgate e conclua ou reembolse o pedido manualmente.
O reembolso falha: leia a mensagem. Comgate rejected the refund: the amount exceeds the refundable amount. significa que o valor é maior que o que ainda pode ser reembolsado; um pagamento em status diferente de PAID não pode ser reembolsado. Comgate could not be reached. The refund was not made — please try again later. significa um problema de conexão.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações do gateway e os arquivos de log são removidos somente se Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos e os dados da Comgate neles são sempre mantidos. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Comgate é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Comgate.