VibeFox EveryPay for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Conta EveryPay: você precisa do nome de usuário da API, do secret da API e do nome da conta de processamento (processing account) da sua loja virtual. Eles aparecem no EveryPay Merchant Portal, nas configurações da loja virtual. O portal de demonstração (modo de teste) e o portal de produção têm credenciais separadas. Os métodos de pagamento que o cliente pode usar (cartões, Apple Pay, Google Pay, vínculos bancários) são os habilitados para a sua conta EveryPay.

Moeda: uma conta de processamento cobra apenas uma moeda. O nome da conta começa com o código da moeda dela; por exemplo, EUR3D1 cobra em euros. O EveryPay só é oferecido quando o cliente paga nessa moeda.

Site público: a URL de callback da sua loja precisa estar acessível pela internet, sem ser bloqueada por autenticação básica ou por firewall.

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

Instalação

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

OpenCart 3

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

2. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox EveryPay 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 o 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 nome de usuário da API de teste, o secret da API de teste e o nome da conta de processamento do portal de demonstração. Copie a Callback notification URL para o EveryPay Merchant Portal (veja Configuração).

5. Ative Enable/Disable e clique em Save. Faça um pedido de teste no modo de teste; depois, informe as credenciais de produção e desative Test Mode.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_everypay_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 EveryPay Payment, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença, as credenciais do EveryPay e o callback como nos passos 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL do callback é diferente (veja Notificações de pagamento (callback)).

Uma instalação nova começa com o método de pagamento desativado e o modo de teste ativado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox EveryPay 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 mostra Test mode is on: payments go to the EveryPay demo environment, no real money is charged. enquanto o modo de teste estiver ativo. Ela avisa quando o método de pagamento está ativado, mas o nome de usuário da API, o secret da API ou a conta de processamento do modo atual estão ausentes (nesse caso o método fica oculto no checkout), e quando a moeda da conta de processamento é diferente da moeda padrão da loja. Sem permissão para modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title deve ter no máximo 128 caracteres, Sort Order deve ser um número inteiro, Total um número não negativo, e a zona geográfica e os status de pedido selecionados devem existir. Caso contrário, um erro indica o campo e nada é salvo. Espaços e quebras de linha nos nomes de usuário, secrets e no nome da conta são removidos.

EveryPay

Enable/Disable: Enable EveryPay 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ê no checkout. Também é o nome do método de pagamento armazenado no pedido. Até 128 caracteres; se deixado vazio, o cliente verá EveryPay. Padrão: EveryPay.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely by card or bank link on the EveryPay payment page.

Sort Order: a posição do EveryPay entre os métodos de pagamento no checkout. Deixe em branco ou informe um número inteiro.

Geo Zone: oferecer o EveryPay somente para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total do carrinho, na moeda padrão da loja, que um pedido precisa atingir para que o EveryPay seja oferecido. Deixe em branco para oferecer o EveryPay em qualquer total.

Conta EveryPay

O nome de usuário da API, o secret da API e o nome da conta de processamento aparecem no EveryPay Merchant Portal (configurações da loja virtual): o portal de demonstração para o modo de teste e o portal de produção para pagamentos reais (a seção traz links para os dois). Os ambientes de teste e de produção têm credenciais separadas.

Test Mode: os pagamentos vão para o ambiente de demonstração do EveryPay com as credenciais de teste; nenhum dinheiro real é cobrado. Padrão: ativado. Desative para receber pagamentos reais com as credenciais de produção. Enquanto estiver ativo, o cliente vê TEST MODE: EveryPay demo environment, no real money is charged. na etapa Confirm Order.

Test API Username: o nome de usuário da API do ambiente de demonstração.

Test API Secret: o secret da API do ambiente de demonstração.

Live API Username: o nome de usuário da API do ambiente de produção.

Live API Secret: o secret da API do ambiente de produção.

Processing Account Name: a sua conta de processamento EveryPay, por exemplo EUR3D1. A conta define a moeda cobrada: o método de pagamento só é oferecido para pedidos nessa moeda.

Os secrets de API salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para remover um secret salvo, marque Clear the saved API secret on save abaixo do campo e clique em Save.

Notificações de pagamento (callback)

O callback informa à sua loja que um pagamento foi finalizado, para que os pedidos sejam confirmados mesmo que o cliente feche o navegador. Copie a URL exibida em Callback notification URL para o campo de URL de callback da sua loja virtual no EveryPay Merchant Portal, tanto no portal de demonstração quanto no de produção. No OpenCart 3, a URL tem este formato: https://your-store/index.php?route=extension/payment/wcp_everypay_payment/callback; no OpenCart 4, este: https://your-store/index.php?route=extension/wcp_everypay_payment/payment/wcp_everypay_payment.callback. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Copie a URL exatamente como as configurações a mostram.

O callback traz apenas as referências do pagamento. A extensão nunca confia nele sozinho: ela consulta a API do EveryPay sobre o status do pagamento com as credenciais do modo em que o pagamento foi feito. Um callback para um pagamento que esta loja não criou é rejeitado sem nenhuma requisição ao EveryPay. O callback também funciona enquanto a loja está em modo de manutenção, porque o OpenCart 3 deixa passar as requisições das extensões de pagamento e, no OpenCart 4, a extensão adiciona para isso uma ação de inicialização (também para o retorno do cliente). Sem o callback, um pedido recebe seu status quando o cliente volta à loja ou quando você clica em Check EveryPay payment status na página do pedido.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (pedido ausente). Ele recebe um status somente depois que o EveryPay confirma o pagamento pela API. Cada um dos campos abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status do pedido definido após um pagamento verificado como liquidado ou autorizado. Padrão: Processando.

Manual Review Status: o pagamento foi feito, mas o valor ou a moeda não correspondem ao pedido, o pedido foi cancelado nesse meio-tempo ou usa outro método de pagamento. Uma observação explica o motivo, e o pedido não é marcado como pago. Padrão: Pendente, pois o OpenCart não tem o status On hold. Você pode criar um status próprio em System > Localisation > Order Statuses e selecioná-lo aqui.

Cancelled Order Status: um pagamento que chega para um pedido com este status é enviado para revisão manual em vez de quitar o pedido. Padrão: Cancelado.

Avançado

Debug log: registra os eventos de pagamento em wc_evp_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para wc_evp_debug.old.log.php. Erros e avisos são sempre registrados. Secrets de API, e-mails e dados de cartão nunca são registrados. Padrão: desativado.

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

Delete data on uninstall: quando ativado, desinstalar a extensão exclui as configurações do gateway e o log. Os dados de pagamento EveryPay dos pedidos são sempre mantidos. Padrão: desativado.

Importação / Exportação

Export: Download JSON salva as configurações em um arquivo JSON. Os secrets de API não são exportados.

Import: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações. Os secrets de API salvos são mantidos.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, EveryPay). Na etapa Confirm Order, o cliente vê a sua descrição e a observação You will be redirected to the secure EveryPay payment page. O OpenCart cria o pedido nessa etapa, ainda sem status. 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. Quando o cliente clica em Confirm Order, a extensão cria um pagamento EveryPay único para o total do pedido na moeda do pedido, com o e-mail do cliente e o endereço de pagamento, e envia o cliente para a página de pagamento do EveryPay. O idioma da página acompanha o idioma da loja do cliente (inglês, estoniano, russo, letão, lituano, finlandês ou alemão; caso contrário, inglês). Ali, o cliente paga com um dos métodos habilitados para a sua conta EveryPay.

Depois de pagar, o cliente retorna à sua loja. O pedido só é marcado como pago quando o EveryPay confirma: a extensão consulta a API do EveryPay sobre o status do pagamento no retorno do cliente e no callback. O pedido então recebe seu status da forma padrão do OpenCart, com os e-mails de pedido habituais e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart. Se o EveryPay ainda estiver processando o pagamento, ou se a API não puder ser acessada naquele momento, uma página Payment confirmation mostra Your payment is being confirmed by EveryPay. You will receive an e-mail as soon as the order is confirmed. e um botão Check again; o callback define o status do pedido assim que o EveryPay confirma o pagamento.

Se o pagamento falhar, o cliente volta ao checkout com Your EveryPay payment was not successful. Please try again or choose another payment method. Se o cliente saiu da página de pagamento sem pagar, a mensagem é The EveryPay payment was not completed. You can try again or choose another payment method. O carrinho é mantido e o pedido permanece sem status. No OpenCart 4, essas mensagens aparecem acima da página de finalização de compra.

No OpenCart 3, um novo pedido é criado sempre que a etapa Confirm Order é exibida; no OpenCart 4, o pedido da finalização de compra é atualizado, de modo que uma nova tentativa paga o mesmo pedido com um novo pagamento EveryPay. O EveryPay não pode cancelar um pagamento depois de criado. Por isso, antes de um novo pagamento, a extensão verifica com a API do EveryPay as tentativas abertas deste pedido e de outros pedidos do mesmo carrinho. Se uma delas já estiver paga, ou se outro pedido do mesmo carrinho já estiver pago, o cliente vai para a página de sucesso sem um segundo pagamento. Cada tentativa fica registrada, de modo que um pagamento feito com um link mais antigo também é reconhecido. Se o cliente pagar mesmo assim um segundo pedido do mesmo carrinho (por exemplo, a partir de duas abas abertas do navegador), esse pedido não recebe status, o cliente vê a página de sucesso do pedido, e o pedido pago recebe uma observação pedindo que você estorne o segundo pagamento no EveryPay Merchant Portal.

No OpenCart 4, o pedido permanece no checkout até a página de sucesso ser exibida. Se, nesse meio-tempo, esse pedido foi fechado sem pagamento (por exemplo, se você o cancelou), o cliente volta à finalização de compra com a mensagem Your previous order was cancelled. Please confirm the order again., e o próximo Confirm Order paga um novo pedido do carrinho. Se esse pedido já estiver pago, mas o carrinho tiver mudado desde então, inclusive a quantidade, a mensagem é Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. Um pedido pago nunca é mostrado como pago para um carrinho diferente.

Se o EveryPay não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão, por exemplo EveryPay is temporarily unavailable. Please try again in a moment or choose another payment method. Os detalhes ficam no log.

A extensão aceita apenas pagamentos únicos. Não há reembolsos ou capturas a partir da loja, cartões salvos ou pagamentos com um clique, assinaturas ou pagamentos recorrentes, campos de cartão incorporados nem multimoeda.

Pedidos

Status do pedido

No status (missing order): o cliente foi enviado ao EveryPay e não pagou, o pagamento falhou ou foi abandonado, ou o EveryPay 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): o EveryPay informou que o pagamento foi liquidado ou autorizado. Uma observação mostra o valor, a moeda e a referência do pagamento. Para um pagamento autorizado, a observação informa que os valores estão reservados: se a sua conta não captura automaticamente, capture o pagamento no EveryPay Merchant Portal. Quando ele for liquidado depois, uma observação avisa.

Manual Review Status (default Pending): o pagamento precisa de revisão manual. O valor ou a moeda pagos não correspondem ao pedido, o pedido tinha o Cancelled Order Status antes da chegada do pagamento, ou o pedido agora usa outro método de pagamento. A observação explica isso e informa que o pedido não foi marcado como pago. Confira o pagamento no Merchant Portal e então atenda ou estorne o pedido manualmente. Callbacks posteriores desse pagamento não concluem o pedido automaticamente; um pagamento correto de outra tentativa do mesmo pedido, porém, o quita.

Se um segundo pagamento for concluído para um pedido que já está pago, o pedido não é alterado. Uma observação pede que você estorne o pagamento duplicado no EveryPay Merchant Portal. As observações são entradas do History do pedido que o cliente não vê.

Aba VibeFox EveryPay Payment

Em Sales > Orders, abra um pedido pago com o EveryPay. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox EveryPay Payment mostra os EveryPay payments of this order: Payment reference, Order reference, Mode (teste ou produção), Amount, EveryPay state, Result e Date de cada tentativa. Abaixo ficam as EveryPay notes do pedido. A aba é exibida para os usuários que têm acesso à extensão.

Check EveryPay payment status: o botão da aba lê da API o status de cada pagamento EveryPay do pedido, do mais recente para o mais antigo, com as credenciais do modo de cada um; aplica o resultado como descrito acima e adiciona uma observação com o status de cada pagamento. Depois, a aba é recarregada. Você precisa da permissão para modificar pedidos (System > Users > User Groups); a permissão para modificar a extensão não é necessária. Use-o quando um callback nunca chegou, por exemplo para ver uma captura ou um estorno posterior. Um status definido por esse botão é gravado como uma alteração manual de status no painel administrativo, sem os e-mails de pedido nem a atualização de estoque do checkout.

Reembolsos

Reembolsos e capturas a partir da loja não são suportados. Estorne no EveryPay Merchant Portal e, depois, atualize o status do pedido no OpenCart. Quando o EveryPay informa que um pagamento foi estornado ou sofreu chargeback, a extensão apenas adiciona uma observação ao pedido; o status do pedido não muda. Devoluções de produtos em Sales > Returns não devolvem dinheiro pelo EveryPay.

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 EveryPay Payment é o primeiro bloco de Extensions > Extensions > Payments > VibeFox EveryPay 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 de novo, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: opencart-payment-everypay e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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 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, a extensão continua funcionando com o último status conhecido.

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

Sem uma chave ativa, o EveryPay não é mostrado aos clientes no checkout. 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 ao painel administrativo 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 enxerga o login do painel administrativo, de modo que, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel administrativo. 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 do painel administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

EveryPay does not appear at checkout: verifique se a licença está ativa, se Enable/Disable está ativado, se o nome de usuário da API, o secret da API e o Processing Account Name do modo atual estão preenchidos, e se o cliente paga na moeda da conta de processamento. A página de configurações mostra um aviso nesses casos. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

The payment went through, but the order stays without a status: o callback não está funcionando. Verifique se a URL de Callback notification URL está configurada no Merchant Portal do modo que você usa (demonstração ou produção) e se ela abre a partir da internet. O pedido também recebe seu status quando o cliente volta à loja depois de pagar. Veja o campo Log na página da extensão: erros são sempre registrados.

Callback answers Unknown payment, Unknown payment reference, Payment cannot be verified or Payment does not belong to this order: o pagamento não foi criado por esta loja ou para este pedido, ou a resposta do EveryPay não corresponde a ele. Nada é alterado.

Callback answers Missing or invalid payment_reference: a requisição não trazia uma referência de pagamento válida, por exemplo quando a URL é aberta em um navegador.

Callback answers Not configured: faltam as credenciais do ambiente onde o pagamento foi criado, por exemplo um pagamento de teste depois que as credenciais de teste foram removidas. Informe-as novamente; o EveryPay repete o callback.

Callback answers Payment status unavailable, Busy, please retry or Processing error, please retry: a API do EveryPay não pôde ser acessada, o pedido estava sendo processado por outra requisição naquele mesmo momento, ou o processamento falhou. O motivo está no log. O EveryPay repete o callback.

The customer sees This payment method is not available right now: faltam as credenciais ou a conta de processamento do modo atual.

The customer sees EveryPay is temporarily unavailable or Unable to start the EveryPay payment: o EveryPay recusou as credenciais ou não pôde ser acessado. Verifique o nome de usuário e o secret da API do modo atual.

The customer sees This payment method does not support the order currency: a moeda do pedido é diferente da moeda da conta de processamento.

The customer stays on the Payment confirmation page: o EveryPay ainda não finalizou o pagamento. O pedido recebe seu status pelo callback, ou quando o cliente clica em Check again depois que o EveryPay confirma o pagamento.

Order is in the review status: leia as EveryPay notes na aba VibeFox EveryPay Payment. O valor ou a moeda não correspondiam, o pedido havia sido cancelado antes da chegada do pagamento, ou ele usa outro método de pagamento. Confira o pagamento no Merchant Portal e então atenda ou estorne o pedido manualmente.

Para desenvolvedores: antes de o pagamento ser criado, a extensão dispara os eventos do OpenCart wc_evp_oneoff_request (alterar a requisição de pagamento) e wc_evp_locale (alterar o idioma da página de pagamento).

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox EveryPay Payment. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre 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, que voltam aos valores padrão em uma reinstalação. No OpenCart 4, também são removidos o evento da extensão (a mensagem do checkout) e a sua ação de inicialização, que deixa passar o callback e o retorno do cliente no modo de manutenção. Se a chave Uninstall em Advanced estiver ativada, as demais configurações do gateway (título, descrição, modo de teste, credenciais, conta de processamento, log de depuração) e o log são removidos. Se estiver desativada, eles são mantidos para uma reinstalação posterior. Os dados de pagamento EveryPay dos pedidos são sempre mantidos, de modo que callbacks tardios de pedidos antigos continuam funcionando após uma reinstalação. Os pedidos existentes mantêm suas observações de pagamento.

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

EveryPay é uma marca de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pelo EveryPay.