VibeFox Autopay for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e posterior (testado na versão 4.1.0.3).

PHP: 8.0 ou posterior.

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 do comerciante da Autopay: portal.autopay.eu para produção e testportal.autopay.eu para testes. 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 pedido 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 nem firewall que bloqueie requisições POST. O modo de manutenção não bloqueia as notificações, porque o OpenCart libera as requisições das extensões de pagamento.

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

Instalação

O download é um único arquivo zip com os pacotes das duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3, wcp_autopay_payment-oc3-(version).ocmod.zip, e o pacote do OpenCart 4, wcp_autopay_payment.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_autopay_payment-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, portanto Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload do arquivo para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Autopay Payment e clique em Install (o botão verde +). Seu usuário administrador precisa ter permissão para modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, 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 a URL ITN, a URL de retorno e a função hash SHA-256 do seu serviço (veja Configuração).

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

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_autopay_payment.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Autopay Payment, clique em Install (o botão verde +) e depois em Edit (o botão com lápis).

4. Informe a chave de licença e as configurações como nas etapas 3 a 6 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só os endereços de ITN e de retorno são diferentes (veja Endereços de ITN e de retorno).

Uma nova instalação começa com o método de pagamento desativado, o modo de teste ativado e o PLN como única moeda.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa quando o Service ID ou a Shared key do ambiente selecionado estão vazios (nesse caso o método de pagamento fica oculto na finalização de compra) e quando a moeda padrão da loja não está selecionada em Currencies (nesse caso o método de pagamento fica oculto nessa moeda). Enquanto o modo de teste estiver ativo, ela mostra Test mode is on: payments go to the Autopay test environment (testpay.autopay.eu), no real money is taken. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title deve ter de 1 a 128 caracteres, Sort Order deve ser um número inteiro, Total deve ser um número igual ou maior que 0, e um Service ID só pode conter letras, dígitos, hifens e sublinhados. Se algum campo tiver erro, nada é salvo e a página indica o campo.

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 os clientes veem na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Autopay. Obrigatório, até 128 caracteres.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

Sort Order: a posição da Autopay entre os métodos de pagamento da finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: mostrar a Autopay apenas para endereços de pagamento da zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir antes que a Autopay seja oferecida. Deixe em branco para oferecer a Autopay em qualquer valor.

Serviço Autopay

O Service ID e a Shared key são exibidos no portal do comerciante da Autopay (portal.autopay.eu ou testportal.autopay.eu, com links 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-o para receber pagamentos reais em pay.autopay.eu com as credenciais de produção. Enquanto estiver ativo, os clientes veem Test mode: no real payment is taken. na etapa Confirm Order.

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-a 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.

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 apenas para alterá-lo. Para remover uma chave salva, marque Clear the saved key on save abaixo do campo e clique em Save.

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 da finalização de compra está selecionada aqui. Padrão: PLN.

Endereços de ITN e 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 e são montados a partir do endereço da loja da sua instalação do OpenCart:

Estes são os endereços do OpenCart 3. No OpenCart 4 eles são:

Copie os endereços exatamente como as configurações os mostram. Sem a URL de ITN, os pedidos nunca são confirmados: o OpenCart mantém o pedido sem status até que a Autopay confirme o pagamento. Cada ITN é verificado com o hash SHA-256 gerado com a Shared key do serviço indicado na notificação. Notificações sem um hash válido ou com um Service ID desconhecido são rejeitadas. Uma notificação só é aplicada a um pedido se o seu pagamento tiver sido iniciado com o mesmo serviço Autopay, de modo que uma notificação de teste nunca confirma um pagamento de produção. Notificações de pagamentos iniciados antes de você trocar o Test mode continuam sendo verificadas com a chave correta, desde que as duas credenciais permaneçam salvas.

A extensão trata estes status de pagamento no ITN:

Orders

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status quando a Autopay confirma o pagamento (ITN SUCCESS). Um pagamento falho ou abandonado deixa o pedido sem status. No OpenCart 4, um pedido não pago da finalização de compra pode receber o status Voided, que o OpenCart 4 define quando o cliente volta à etapa Confirm Order; a extensão trata esse pedido como um pedido sem status, e um ITN SUCCESS posterior ainda o marca como pago. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status definido quando a Autopay confirma o pagamento com o valor e a moeda esperados. Padrão: Processing.

On Hold Status: o valor ou a moeda pagos são diferentes do pedido, ou o pagamento chegou depois que o status do pedido já havia sido alterado (por exemplo, cancelado). O pedido não é marcado como pago; uma nota explica o motivo. Padrão: Pending, porque o OpenCart não tem o status On hold. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Advanced

Logging: grava os eventos de pagamento em wc_ap_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao chegar a 5 MB, é movido para wc_ap_debug.old.log.php. Chaves e dados dos clientes nunca são registrados. Padrão: desativado. Nada é gravado enquanto estiver desativado, erros inclusive.

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

Import / Export

Export: Download JSON salva as configurações em um arquivo JSON. As Shared keys não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As Shared keys salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Autopay). Na etapa Confirm Order, o cliente vê a sua descrição e a nota You will be redirected to the secure Autopay payment page to complete the payment. O OpenCart cria o pedido nesta etapa, ainda sem status. Quando o cliente clica em Confirm Order, o navegador envia à Autopay um formulário de pagamento assinado com o valor total do pedido na moeda do pedido, o número do pedido do OpenCart como OrderID, a descrição Order seguida do 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 o confirma com um ITN assinado e o valor e a moeda correspondem ao pedido. O pedido então recebe o seu status da forma padrão do OpenCart, com os e-mails habituais de pedido e a atualização do estoque. Depois de pagar, o cliente volta para a sua loja. O endereço de retorno é assinado, mas nunca altera um pedido. Se o pedido já tiver um status, o cliente vê a página de sucesso do pedido do OpenCart. Se o ITN ainda não tiver chegado, uma página de Payment confirmation mostra Thank you. Your payment is being confirmed by Autopay — your order is confirmed as soon as Autopay reports the payment, and you will receive an e-mail. com os botões Check again e Back to checkout.

Se a Autopay informou um pagamento falho, o cliente volta à finalização de compra com a mensagem The payment was not completed. You can try again or choose another payment method. O carrinho é mantido. Cada nova tentativa cria um novo pedido do OpenCart (no OpenCart 4, o cliente paga o mesmo pedido de novo, com uma nova tentativa sob o mesmo OrderID). Se outro pedido do mesmo carrinho (os mesmos produtos na mesma visita) já tiver sido pago, o cliente vai para a página de sucesso em vez de pagar de novo. Uma nova compra depois de uma concluída é um novo carrinho e é paga normalmente. Se o pagamento não puder ser iniciado, o cliente permanece na etapa Confirm Order com uma mensagem curta acima do botão, por exemplo Autopay payments are not configured. Please choose another payment method or contact the store. ou que a Autopay não pode aceitar pagamentos nesta moeda.

No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco de métodos de pagamento, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização de compra. A mensagem sobre o pagamento não concluído é exibida acima da página de finalização de compra. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza. Se esse pedido tiver sido fechado pela loja nesse meio-tempo (por exemplo, se você o cancelou), o cliente é enviado de volta à finalização de compra com The payment was not completed. You can try again or choose another payment method., ou, se o pedido tiver sido pago pela Autopay, com Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order. Se o pedido da finalização de compra já estiver pago para um carrinho diferente, a mensagem é Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. O próximo Confirm Order paga um novo pedido. Uma alteração no carrinho, inclusive uma nova quantidade, conta como um novo carrinho que precisa de um pagamento próprio. O ITN também funciona enquanto a loja está em modo de manutenção: no OpenCart 4, a extensão adiciona uma ação de inicialização para isso.

A extensão não tem reembolsos pelo OpenCart, assinaturas ou pagamentos recorrentes, cartões salvos, código BLIK nem formulário de cartão na página de finalização de compra, nem escolha de banco ou canal de pagamento na página de finalização de compra, e usa um Service ID por ambiente.

Pedidos

Order statuses

No status (missing order): o cliente foi enviado para a Autopay e não pagou, o pagamento falhou ou a Autopay ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Order Status After Payment (default Processing): a Autopay confirmou o pagamento e o valor e a moeda correspondem. Uma nota mostra o valor, o ID da transação na Autopay (remoteID) e a data do pagamento.

On Hold Status (default Pending): a Autopay informou um valor ou uma moeda diferentes do total do pedido. 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 posterior correta para este pedido o marca como pago. O mesmo status é usado quando chega um pagamento para um pedido cujo status você alterou nesse meio-tempo, por exemplo cancelado: uma nota pede que você verifique o estoque e atenda o pedido, ou que reembolse o pagamento.

Um pedido pago nunca é alterado por uma notificação de falha posterior. Se a Autopay informar outro pagamento bem-sucedido para um pedido já pago, ou se um segundo pedido do mesmo carrinho for pago, uma nota avisa que o cliente pode ter pago duas vezes. Uma notificação de um pagamento iniciado com outro serviço Autopay não é aplicada, e uma nota explica isso. As notas são registros do History do pedido que o cliente não vê.

VibeFox Autopay Payment tab

Em Sales > Orders, abra um pedido pago com a Autopay. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Autopay Payment mostra o OrderID at Autopay, o Service ID e o ambiente, com a etiqueta Test mode nos pagamentos de teste, o Amount, o status da Payment attempt, o Autopay transaction ID e as Autopay notes do pedido. A aba é somente leitura e é exibida aos usuários que têm acesso à extensão.

Refunds

Reembolsos pela Autopay não são suportados. Reembolse o pagamento no portal da Autopay e depois atualize o pedido no OpenCart manualmente.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Autopay Payment é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit, acima das configurações. Cole 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 aparecem a linha Product: opencart-payment-autopay e o link Manage licenses and domains in your account, que abre a sua conta no vibefox.net. Somente administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma da administração (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 seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar um slot de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera o slot de domínio. Libere o slot na sua conta do vibefox.net.

Sem uma chave ativa, a Autopay 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. Um usuário administrador conectado à administração no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4, essa prévia não está disponível: a loja não vê o login na administração, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard da administração. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente quando você abre o Dashboard ou a página Edit da administração: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar a extensão sempre remove a chave de licença e o status da 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 da finalização de compra está selecionada em Currencies. A página de configurações mostra um aviso quando um destes itens falta. Confira também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O pagamento foi feito, mas o pedido continua sem status: a Autopay não entregou o ITN, ou a loja o 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 da extensão corresponde ao serviço. Verifique se a loja está acessível pela internet. Ative o Logging e veja o campo Log na página da extensão.

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 na extensão, ou cuja Shared key está vazia.

O log mostra could not lock the order, Autopay will retry: o pedido estava sendo processado por outra notificação no mesmo momento. A loja responde para que a Autopay envie a notificação novamente.

A URL de ITN mostra METHOD_NOT_ALLOWED no navegador: isso é normal. A URL aceita apenas requisições POST da Autopay.

O pedido está no status de espera com uma nota de divergência: a Autopay informou um valor ou uma moeda diferentes do total do pedido. 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 de produção. 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 na extensão. O pedido não é afetado; ele segue o ITN.

O cliente vê This payment method is not available. Please reload the checkout page.: a sessão de finalização de compra não corresponde mais ao pedido, ou o método de pagamento foi desativado ou perdeu as credenciais nesse meio-tempo. O cliente recarrega a finalização de compra.

Para desenvolvedores: antes de o formulário de pagamento ser assinado, a extensão dispara o evento do OpenCart wc_ap_payment_params com os parâmetros do formulário e o pedido; o serviço, o número do pedido, o valor e a moeda não podem ser alterados por ele.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Autopay Payment. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders. A extensão sempre remove as demais configurações do gateway, incluindo os Service IDs e as Shared keys, e o log. Não há opção para manter as configurações. No OpenCart 4, também são removidos os eventos da extensão e a sua ação de inicialização, que deixa o ITN passar no modo de manutenção. Os registros de pagamentos da Autopay são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Autopay Payment na lista de extensões instaladas. Depois, clique em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

A Autopay é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Autopay.