VibeFox Comgate for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.

HTTPS: a sua loja precisa estar acessível por HTTPS a partir da internet, para que a Comgate consiga enviar 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 florins inteiros, como exige a Comgate.

Conta na 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 do cliente da Comgate, além da URL de notificação configurada ali (veja Configuração). A Comgate usa o mesmo Merchant ID e o mesmo segredo para pagamentos de teste e reais.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.

Instalação

1. No back office, acesse Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.

2. Quando o envio terminar, clique em Configure ou, depois, encontre VibeFox Comgate Gateway na lista de módulos e clique em Configure.

3. Informe a sua chave de licença VibeFox em License key no bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).

4. Informe o Merchant ID e o Secret do portal do cliente da Comgate e configure lá a URL de notificação (veja Configuração).

5. Ative Enable / Disable e clique em Save. Mantenha o Test Mode ativado para um pagamento de teste e depois desative-o.

Ao ser instalado, o módulo cria o status de pedido Comgate payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Comgate Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando a Comgate está ativada, mas faltam o Merchant ID ou o segredo (nesse caso o método de pagamento fica oculto no checkout até que os dois sejam preenchidos), e quando a moeda padrão da loja não é suportada pela Comgate. 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.

Comgate

Enable / Disable: Enable Comgate Payment Gateway liga ou desliga o método de pagamento. Default: off.

Title: o nome do método de pagamento que o cliente vê no checkout. Ele também é o nome do método de pagamento salvo no pedido. Default: Comgate. Obrigatório.

Description: o texto exibido abaixo do método de pagamento no checkout. Default: Pay securely via Comgate — cards, bank transfers, wallets and more. Em 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

Pegue o identificador da loja (Merchant ID) e a senha (segredo) no portal do cliente 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 em Notification URL nesta seção. Com URLs amigáveis ela fica assim: https://your-shop/module/wcp_comgate_gateway/webhook, possivelmente com um código de idioma, como /en/. Copie a URL exatamente como as configurações a mostram. A Comgate a chama após cada pagamento; o módulo então consulta novamente o pagamento pela API de status da Comgate antes de alterar qualquer coisa. As URLs de retorno para o cliente são enviadas com cada pagamento. Se o portal também pedir URLs de retorno (pago, cancelado, pendente), use a segunda URL exibida nesta seção, que termina em return?id=${id}&refId=${refId}.

Merchant ID: o identificador da loja (merchant) na Comgate.

Secret: a senha para a comunicação em segundo plano (segredo) desta conexão da loja. Um segredo salvo nunca é exibido novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas se quiser alterá-lo.

Limpar o segredo salvo: marque a opção e clique em Save para remover o segredo salvo. Um campo vazio mantém o valor salvo.

Test Mode: cria pagamentos de teste (nenhum valor é cobrado). A Comgate usa o mesmo Merchant ID e o mesmo segredo para pagamentos de teste e reais; os pagamentos de teste são marcados com test=true. Os reembolsos são sempre enviados no modo do pagamento original. Default: on.

Página de pagamento

Payment Methods: quais métodos de pagamento da Comgate o cliente pode escolher. Só são exibidos os métodos ativados para a sua loja na Comgate.

Language: o idioma da página de pagamento da Comgate. Automatic (shop language, English as fallback) (padrão) ou um dos 26 idiomas disponíveis.

Pedidos

Order Status After Payment: o status definido quando a Comgate confirma o pagamento.

Pagamentos que não correspondem ao pedido, pagamentos de teste em modo de produção e pagamentos pré-autorizados sempre vão para Comgate payment on hold.

Avançado

Debug Log: grava as requisições à API e as notificações em logs/comgate_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. O segredo e os dados pessoais nunca são registrados. Os erros são sempre registrados. Default: off.

Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.

Delete Data on Uninstall: quando ativado, desinstalar o módulo remove as configurações do gateway e o log. Os pedidos e os IDs das transações da Comgate são sempre mantidos. Default: off.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Comgate) e confirma o pedido. O módulo cria o pagamento na Comgate pelo total do carrinho, na moeda do carrinho, e redireciona o cliente para a página de pagamento da Comgate. O e-mail e o nome do cliente são enviados à Comgate, e o pagamento é identificado como Cart com o número do carrinho. É obrigatório um e-mail válido. Na página da Comgate, o cliente paga com um dos métodos que você liberou. Neste ponto, ainda não existe nenhum pedido.

Após pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Comgate confirma: o módulo lê o pagamento pela API de status da Comgate, tanto quando chega a notificação em segundo plano quanto quando o cliente retorna. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido. Se o pedido foi colocado em espera, a página acrescenta Your payment is being reviewed. We will contact you if anything else is needed. Se um pedido pré-autorizado foi cancelado depois, a página mostra Your Comgate payment was not completed. Please contact us about this order.

Se o pagamento ainda não estiver confirmado quando o cliente retornar, por exemplo uma transferência bancária em andamento, aparece uma página Payment confirmation com a mensagem Comgate has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again., com um botão Check again e um botão Back to checkout.

Se o pagamento for cancelado ou expirar, o cliente volta à finalização de compra com a mensagem The Comgate payment was cancelled or has expired. You can try again or choose another payment method. O carrinho é mantido. Cada nova tentativa verifica primeiro a anterior, assim um pagamento que já foi concluído não é cobrado duas vezes, e a tentativa anterior é cancelada na Comgate se ainda estiver aberta. Um pagamento tardio de uma tentativa mais antiga ainda cria o pedido.

Se a Comgate não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo The Comgate payment could not be started. Please try again or choose another payment method., informando que a Comgate não pode aceitar este valor ou esta moeda, ou que o método de pagamento da Comgate selecionado não está disponível. O motivo técnico é gravado no log.

A notificação funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.

O módulo aceita pagamentos únicos apenas na página da Comgate. Não há pagamentos recorrentes, assinaturas ou cartões salvos, nem checkout da 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 PrestaShop. Sem a notificação, o status do pagamento não é consultado automaticamente; ele só é verificado quando o cliente retorna.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado à Comgate e ainda não pagou, ou a Comgate informa o pagamento como pendente. Existe apenas o carrinho.

Payment accepted or Delivered: a Comgate informou o pagamento como PAID, com o mesmo valor e a mesma moeda. O status segue Order Status After Payment. O pagamento é registrado com o ID da transação na Comgate. Pagamentos de teste recebem a nota Comgate test payment — no money was charged.

Comgate payment 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 da Comgate). Um pagamento autorizado vira pago automaticamente quando você o captura no portal da Comgate. A nota explica o motivo.

Canceled: um pagamento autorizado foi cancelado ou expirou na Comgate. Se a Comgate confirmar o pagamento depois disso, o pedido é reaberto como pago, com uma nota para verificar o estoque antes do envio.

Refunded: o pagamento foi totalmente reembolsado pelo módulo.

Se a Comgate informar outro pagamento PAID para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você verifique isso no portal da Comgate e reembolse o duplicado. Uma confirmação reenviada nunca reabre um pedido reembolsado.

Bloco de pagamento da Comgate

A página do pedido mostra um bloco Comgate payment com o ID da transação, o status na Comgate, o valor pago, o total do pedido e o valor reembolsado, um selo Test mode para pagamentos de teste, o motivo de uma revisão, o histórico de reembolsos e as Comgate notes do pedido.

Reembolsos

No bloco Comgate payment, informe o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via Comgate. Confirme a pergunta Refund this amount through Comgate? This cannot be undone. São suportados reembolsos totais e parciais. É preciso ter permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. O reembolso é enviado à transação paga na Comgate e no modo (teste ou produção) do pagamento original. A Comgate reembolsa apenas pagamentos PAID e no máximo o valor pago; reembolsos em HUF devem ser em florins inteiros. Se a Comgate não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é acrescentado ao histórico de reembolsos e às notas, com o valor, a transação na Comgate e o motivo. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status.

Reembolsos só estão disponíveis para pedidos pagos. Um pedido em espera após divergência de valor ou moeda não pode ser reembolsado pelo PrestaShop; reembolse-o no portal da Comgate. O módulo não gera notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Comgate. Reembolsos feitos no portal da Comgate não são informados à loja.

Chave de licença

O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Comgate Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Comgate Gateway > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-comgate e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure para o módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).

Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on com uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o domínio da loja principal, inclusive em uma configuração multiloja. Remover a chave da loja 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 é exibida 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. A vitrine do PrestaShop não sabe que você está conectado ao back office, então o método de pagamento também fica oculto para você: você pode configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. Um aviso aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Não é preciso nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

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á ligado, se Merchant ID e Secret estão preenchidos, se a moeda do carrinho é 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). Em Payment > Preferences, verifique se o módulo está liberado para a moeda do carrinho, o país do cliente e o grupo do cliente.

O pagamento foi concluído, mas nenhum pedido foi criado: a Comgate não entregou a notificação em segundo plano. Verifique a URL for passing the payment result no portal da Comgate (exatamente a Notification URL das configurações), se a sua loja está acessível por HTTPS a partir da internet e o log (ative o Debug Log). A Comgate repete as notificações não entregues; o módulo responde com um erro sempre que não processou uma notificação, por isso ela será reenviada. O pedido também é criado quando o cliente volta para a 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ão vazios nas configurações. A Comgate tenta novamente quando eles forem preenchidos.

A notificação responde Unknown transaction, Order not found ou Reference mismatch: a notificação pertence a um pagamento que esta loja não criou para aquele carrinho. Nada é 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 carrinho estava sendo processado por outra requisição no mesmo momento. Busy também é a resposta quando o pedido não pôde ser criado; o motivo está no log. A Comgate tenta a notificação novamente.

A URL de notificação mostra code=1&message=POST%20required no navegador: isso é normal. A URL aceita apenas requisições da Comgate.

O cliente vê We could not verify the Comgate payment: o link de retorno não correspondeu ao carrinho. Se o valor foi cobrado, a notificação ainda cria o pedido. Verifique o pagamento no portal da Comgate antes que o cliente pague de novo.

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 carrinho não pode ser pago com a Comgate do jeito que está.

O pedido fica em Comgate payment on hold após o pagamento: leia as notas no bloco Comgate payment. O valor ou a moeda pagos eram diferentes, chegou um pagamento de teste 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 no bloco. Comgate rejected the refund: the amount exceeds the refundable amount. significa que o valor é maior do 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.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Comgate Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete Data on Uninstall estiver ativado, as configurações do gateway e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação futura. As transações e os reembolsos da Comgate e o status de pedido Comgate payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e os IDs das transações.

A Comgate é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado à Comgate nem endossado por ela.