VibeFox Autopay for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.

Serviço Autopay: você precisa do Service ID e da Shared key (chave hash) do seu serviço Autopay. Eles são exibidos no portal de merchant da Autopay: portal.autopay.eu para produção e testportal.autopay.eu para teste. Os serviços de teste têm Service ID e Shared key próprios; peça à Autopay para abrir um. A função hash do serviço deve ser SHA-256.

Moeda: a moeda do carrinho deve ser PLN, EUR, GBP, USD ou CZK e ser aceita pelo seu serviço Autopay.

Loja acessível: a Autopay precisa conseguir enviar notificações para a sua loja, por isso ela deve estar acessível pela internet, sem autenticação básica e sem um firewall que bloqueie requisições POST. O modo de manutenção e a restrição por país da sua loja não bloqueiam as notificações.

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

Instalação

1. No back office, vá em 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 Autopay Payment na lista de módulos e clique em Configure.

3. Informe 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 Service ID e a Shared key (teste e produção) e escolha as moedas do seu serviço.

5. No portal da Autopay, defina para o seu serviço a URL de ITN, a URL de retorno e a função hash SHA-256 (veja Configuração).

6. Ative Enable/Disable e clique em Save. Faça um pedido de teste no modo de teste e, depois, desative Test mode para pagamentos reais.

Na instalação, o módulo cria o status de pedido Autopay payment on hold. O PrestaShop habilita o 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 Autopay Payment > 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 o Service ID ou a Shared key do ambiente selecionado estão vazios, e quando a moeda padrão da loja não está selecionada em Currencies. Nos dois casos, o método de pagamento fica oculto na finalização de compra (para a moeda não selecionada).

Autopay

Enable/Disable: Enable Autopay 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. Também é o nome do método de pagamento salvo no pedido. Padrão: Autopay. Obrigatório.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

Serviço Autopay

O Service ID e a Shared key são exibidos no portal de merchant da Autopay (portal.autopay.eu ou testportal.autopay.eu, com link nesta seção).

Test mode: usa o ambiente de teste da Autopay (testpay.autopay.eu) e as credenciais de teste abaixo. Padrão: ativado. Desative para aceitar pagamentos reais em pay.autopay.eu com as credenciais de produção.

Service ID (production): o identificador numérico do serviço em portal.autopay.eu.

Shared key (production): a chave hash do serviço de produção. Mantenha em sigilo.

Service ID (test): o identificador numérico do serviço em testportal.autopay.eu.

Shared key (test): a chave hash do serviço de teste.

Ao salvar, um Service ID com caracteres diferentes de letras, dígitos, hífens ou sublinhados é recusado com erro, e nada é salvo. As Shared keys salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.

Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Currencies: as moedas que o seu serviço Autopay aceita: PLN, EUR, GBP, USD, CZK. A Autopay normalmente abre um serviço separado por moeda. O método de pagamento só é oferecido quando a moeda do carrinho está selecionada aqui. Padrão: PLN.

Notificações de pagamento (ITN) e endereço de retorno

Informe estes endereços no portal da Autopay para o seu serviço, tanto para produção quanto para teste. Os endereços exatos são exibidos no campo Addresses desta seção. Com URLs amigáveis, eles ficam assim, possivelmente com um código de idioma como /en/:

Copie os endereços exatamente como as configurações os exibem. Sem a URL de ITN, os pedidos nunca são criados, porque o PrestaShop cria o pedido somente quando a Autopay confirma o pagamento. Cada ITN é verificada com o hash SHA-256 gerado com a Shared key do serviço indicado na notificação. Notificações sem hash válido ou com Service ID desconhecido são rejeitadas. Uma notificação só é aplicada a um carrinho se o pagamento foi iniciado com o mesmo serviço Autopay, portanto uma notificação de teste nunca confirma um pagamento de produção. Notificações de pagamentos iniciados antes de você alternar o Test mode continuam sendo verificadas com a chave correta, desde que as duas credenciais permaneçam salvas.

O módulo trata estes status de pagamento na ITN:

Avançado

Logging: grava os eventos de pagamento em logs/wc_ap_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves e dados do cliente nunca são registrados. Padrão: desativado. Enquanto estiver desativado, nada é gravado, nem mesmo erros.

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

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Autopay) com a sua descrição e confirma. A página seguinte exibe Thank you. You are being redirected to Autopay to complete the payment. Your order is created as soon as Autopay confirms it. e envia o cliente à página de pagamento da Autopay. Se o cliente voltar com o botão voltar do navegador, a página exibe o botão Pay with Autopay em vez de redirecionar de novo. Neste ponto, ainda não existe pedido.

O módulo envia o total do carrinho na moeda do carrinho, o número do carrinho como referência do pedido, a descrição (Cart e o número) e o e-mail do cliente. Na página da Autopay, o cliente escolhe o método de pagamento e paga.

O pedido só é marcado como pago depois que a Autopay confirma com uma ITN assinada e o valor e a moeda correspondem ao carrinho. Em seguida, o pedido é criado e o cliente recebe os e-mails padrão do PrestaShop. Depois de pagar, o cliente retorna à sua loja. O endereço de retorno é assinado, mas nunca cria nem altera um pedido. Se o pedido já existir, o cliente vê a página padrão de confirmação do pedido. Se a ITN ainda não tiver chegado, uma página de Payment confirmation exibe Thank you. Your payment is being confirmed by Autopay — your order will be created as soon as Autopay confirms it, and you will receive an e-mail. com os botões Check again e Back to checkout.

Se a Autopay informou um pagamento com falha, o cliente volta à finalização de compra com The payment was not completed. You can try again or choose another payment method. O carrinho é mantido. Se o pagamento não puder ser iniciado, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Autopay payments are not configured. Please choose another payment method or contact the store. ou informando que a Autopay não pode aceitar pagamentos nesta moeda.

O módulo não faz reembolsos pelo PrestaShop, não tem assinaturas nem pagamentos recorrentes, não salva cartões, não tem código BLIK nem formulário de cartão na finalização de compra, não permite escolher banco ou canal de pagamento na finalização de compra, e usa um Service ID por ambiente.

Pedidos

Status do pedido

No order yet: o cliente foi enviado à Autopay e não pagou, o pagamento falhou ou a Autopay ainda não confirmou o pagamento. Só existe o carrinho.

Payment accepted: a Autopay confirmou o pagamento, e o valor e a moeda coincidem. O pagamento é registrado com o ID da transação Autopay (remoteID) como ID da transação, e uma nota mostra o valor, a transação da Autopay e a data do pagamento.

Autopay payment on hold: a Autopay informou um valor ou uma moeda diferentes do total do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou). O pedido não é marcado como pago. Verifique a transação no portal da Autopay e conclua-a ou reembolse-a manualmente. Uma notificação correta posterior para este pedido o marca como pago. O mesmo status é usado quando chega um pagamento para um pedido que havia sido cancelado: o pagamento é registrado e uma nota pede que você verifique o estoque e atenda o pedido, ou reembolse o pagamento.

Um pedido pago nunca é alterado por uma notificação posterior de falha. Se a Autopay informar outro pagamento bem-sucedido para um pedido pago, uma nota avisa que o cliente pode ter pago duas vezes. Uma notificação de pagamento iniciado com outro serviço Autopay não é aplicada, e uma nota explica isso. As notas são visíveis apenas à equipe, no bloco Autopay payment da página do pedido.

Bloco Autopay payment

A página do pedido exibe um bloco Autopay payment com o OrderID da Autopay, o Service ID e o ambiente, o valor e a moeda, o status do pagamento, o ID da transação Autopay, um selo Test mode para pagamentos de teste e as Autopay notes do pedido. O bloco é somente leitura.

Reembolsos

Reembolsos pela Autopay não são suportados. Reembolse o pagamento no portal da Autopay e, depois, registre-o no PrestaShop com as ferramentas padrão de pedidos.

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 Autopay Payment é o primeiro bloco de Modules > Module Manager > VibeFox Autopay Payment > 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-autopay e o link Manage licenses and domains in your account, que abre sua conta em vibefox.net. Somente funcionários com a permissão Configure do 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 de 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, também em configurações com várias lojas. 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 de licença ativa, a Autopay 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 loja 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 lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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, depois uma vez por semana. Não é necessária nenhuma tarefa cron. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status de licença.

Solução de problemas

A Autopay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o ambiente selecionado tem Service ID e Shared key e se a moeda do carrinho está selecionada em Currencies. A página de configurações exibe um aviso quando algum desses itens falta. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.

O pagamento foi feito, mas nenhum pedido foi criado: a Autopay não entregou a ITN, ou a loja a rejeitou. Verifique se a URL de ITN exibida nas configurações está definida para o serviço no portal da Autopay (produção ou teste), se a função hash é SHA-256 e se a Shared key no módulo corresponde ao serviço. Verifique se a loja está acessível pela internet. Ative o Logging e veja o campo Log na página do módulo.

O log mostra ITN rejected: invalid hash: a Shared key não corresponde ao serviço, ou a função hash do serviço não é SHA-256.

O log mostra que o Service ID não está configurado: a notificação veio de um serviço cujo Service ID não está informado no módulo, ou cuja Shared key está vazia.

O log mostra could not lock the cart, Autopay will retry: o carrinho estava sendo processado por outra notificação no mesmo momento. A loja responde para que a Autopay envie a notificação novamente. O mesmo acontece quando o pedido não pôde ser criado, por exemplo porque o módulo está desativado.

O pedido está em Autopay payment on hold com nota de divergência: a Autopay informou um valor ou uma moeda diferentes do total do carrinho. Verifique a transação no portal da Autopay e conclua ou reembolse o pedido manualmente.

Uma nota diz que a notificação NÃO foi aplicada: o pagamento deste pedido não foi iniciado com este serviço Autopay, por exemplo uma notificação de teste para um pedido real. Verifique a transação no portal da Autopay.

Depois de pagar, o cliente cai na página inicial: o endereço de retorno não pôde ser verificado, por exemplo porque o Service ID não está informado no módulo. O pedido não é afetado; ele segue a ITN.

O cliente vê This payment method is not available.: o método de pagamento não é oferecido para este carrinho (desativado, credenciais ausentes, moeda não selecionada ou não permitido em Payment > Preferences).

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Autopay Payment e escolha Uninstall. A chave de licença e o status de licença deste módulo são sempre removidos. As configurações do módulo, incluindo as chaves, e o log são removidos. O módulo não tem opção para manter as configurações. Os dados de pagamento da Autopay e o status de pedido Autopay payment on hold são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

A Autopay é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Autopay.