VibeFox eWAY 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, com a extensão cURL.

Moeda: AUD, NZD, SGD, HKD ou MYR. Para outras moedas da finalização de compra, o método de pagamento fica oculto no checkout. O pagamento é cobrado na moeda do pedido.

Conta eWAY: você precisa de uma conta de comerciante eWAY com acesso à Rapid API e da sua chave e senha da Rapid API, disponíveis no MyeWAY, em Settings, API Key. Para testes, é preciso uma conta sandbox do eWAY com chave e senha próprias. As chaves de sandbox e de produção são diferentes. Nada precisa ser configurado no MyeWAY: a URL de retorno é enviada com cada pagamento.

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 das duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 wcp_eway_payment_gateway-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_eway_payment_gateway.ocmod.zip. Instale apenas 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_eway_payment_gateway-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 eWAY Payment Gateway 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 a chave e a senha da API sandbox, mantenha Sandbox Mode ativado, ative Enable/Disable, clique em Save e faça um pedido de teste.

5. Informe a chave e a senha da API de produção, desative Sandbox Mode e clique em Save.

6. Opcionalmente, adicione a URL de cron mostrada na página de configurações aos cron jobs do seu servidor (veja Configuração).

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_eway_payment_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo 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 eWAY Payment Gateway, 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 chaves da eWAY e a URL de cron como nos passos 3 a 6 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Apenas a URL de cron é diferente (veja Re-check of lost returns (cron)).

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

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, um selo indica o modo: SANDBOX — payments go to the eWAY sandbox, no real money is charged. ou LIVE — real payments are taken with the live API key. A página avisa quando a chave ou a senha da API do modo atual estão ausentes (nesse caso o método de pagamento não é exibido no checkout) e quando a moeda padrão da loja não é suportada pelo eWAY. 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 de 1 a 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, nada é salvo e a página indica o que corrigir.

eWAY

Enable/Disable: Enable eWAY 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. Padrão: Credit Card (eWAY). 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 securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

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

Geo Zone: oferecer o eWAY 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 eWAY seja oferecido. Deixe em branco para oferecer o eWAY em qualquer total.

Credenciais da API

A chave e a senha da Rapid API ficam no MyeWAY, em Settings, API Key. O eWAY tem guias para as chaves de produção e de sandbox, vinculados nesta seção. As chaves de sandbox e de produção são diferentes. O modo sandbox usa somente as credenciais de sandbox, e o modo de produção somente as credenciais de produção.

Sandbox Mode: os pagamentos vão para a sandbox do eWAY com a chave e a senha de sandbox. Nenhum dinheiro real é cobrado. Padrão: ativado. Desative para receber pagamentos reais com a chave de produção. Enquanto estiver ativo, o cliente vê Test mode: no real payment is taken. na etapa Confirm Order.

Live API Key: a chave da Rapid API da sua conta eWAY de produção.

Live API Password: a senha da Rapid API da sua conta eWAY de produção.

Sandbox API Key: a chave da Rapid API da sua sandbox eWAY (conta de parceiro/desenvolvedor).

Sandbox API Password: a senha da Rapid API da sua conta sandbox eWAY.

Chaves e senhas 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. Para remover um valor salvo, marque Clear the saved value on save abaixo do campo e clique em Save.

Return URL: mostra o endereço de retorno da extensão. Ele é enviado automaticamente ao eWAY com cada pagamento, junto com o pedido e uma chave aleatória da tentativa de pagamento; por isso não há nada a configurar no MyeWAY. O resultado de um pagamento é sempre consultado no eWAY, de servidor para servidor.

Re-check of lost returns (cron): uma URL de cron opcional, exibida abaixo da Return URL. Chame-a a partir de um cron job do servidor a cada 15 minutos, por exemplo com curl. Se um cliente pagar e fechar o navegador antes de voltar à loja, o pagamento é consultado no eWAY cerca de 60 minutos depois de o cliente ser enviado ao eWAY, e o pedido é atualizado. Se o eWAY não puder ser acessado, a verificação é repetida até três vezes. Mantenha esta URL em sigilo: ela contém um token secreto criado na instalação, e uma chamada com token incorreto recebe a resposta Forbidden. No OpenCart 4, a URL tem esta forma: https://your-store/index.php?route=extension/wcp_eway_payment_gateway/payment/wcp_eway_payment_gateway.cron&token=(token).

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (pedido ausente). O pedido só recebe um status depois que o eWAY confirma o pagamento. Cada um dos campos abaixo lista os seus status de pedido do OpenCart.

Order Status on Success: o status definido quando o eWAY confirma o pagamento. Padrão: Processando.

eWAY payment on hold status: o status para um pagamento aprovado que precisa da sua revisão: o valor ou a moeda não correspondem ao pedido, o pagamento foi aprovado depois que o cliente clicou em Cancel na página do eWAY, ou o pedido já tinha outro status. Uma observação no histórico do pedido explica o motivo. 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.

Refunded order status: o status depois que o pagamento é estornado integralmente pela página do pedido. Padrão: Reembolsado.

Avançado

Debug log: grava as chamadas à API e os resultados dos pagamentos em eway_p_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 eway_p_debug.old.log.php. Dados de cartão, chaves, senhas, e-mails dos clientes e códigos de acesso nunca são registrados. Erros são sempre registrados. Padrão: desativado.

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

Delete all extension data on uninstall: quando ativado, desinstalar a extensão remove as configurações do gateway e o log. Os registros de pagamentos e estornos do eWAY dos pedidos são sempre mantidos. Padrão: desativado.

Importação / Exportação

Export: Download JSON salva as configurações em um arquivo JSON. Chaves e senhas da API não são exportadas.

Import: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves e senhas da API salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Credit Card (eWAY)). Na etapa Confirm Order, o cliente vê a sua descrição e a observação You will be redirected to the secure eWAY payment page to pay by card. 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 do método de pagamento, na janela Payment method options, e clica em Confirm Order na parte de baixo da página de finalização de compra. Quando o cliente clica em Confirm Order, a extensão pede ao eWAY uma página de pagamento para o total do pedido na moeda do pedido, com OC- e o número do pedido como referência da fatura, além do endereço de pagamento e do e-mail do cliente, e envia o cliente para a página segura do eWAY (Responsive Shared Page). Ali, o cliente paga com cartão. O valor é cobrado imediatamente.

Depois de pagar, o cliente retorna à sua loja. A extensão não confia no navegador: ela consulta no eWAY, de servidor para servidor, o resultado da página de pagamento criada para este pedido. O pedido só é marcado como pago quando o eWAY confirma e o valor e a moeda aprovados correspondem ao pedido. 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. Para um pedido em espera, a página mostra também Your payment was received and is being reviewed by the store. We will contact you if anything is needed.

Se o eWAY não puder ser consultado naquele momento, uma página Payment confirmation mostra We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again. com um botão Check again e um botão Back to checkout. O pedido recebe seu status quando o cliente verifica novamente ou quando a URL de cron é executada.

Se o pagamento for recusado, o cliente volta ao checkout com o motivo, por exemplo Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. O pedido permanece sem status. Se o cliente clicar em Cancel na página do eWAY, a extensão primeiro confirma com o eWAY que nada foi pago (por exemplo, em outra aba). Depois, o cliente vê You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. Se o pagamento não foi concluído, a mensagem é The payment was not completed. Please try again. O carrinho é mantido em todos os casos. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra.

O cliente pode tentar de novo. O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida, enquanto o OpenCart 4 atualiza o pedido do checkout, por isso uma nova tentativa abre uma nova página de pagamento da eWAY para o mesmo pedido. Antes de criar uma nova página de pagamento, as páginas anteriores deste pedido e de outros pedidos do mesmo carrinho são verificadas no eWAY. Se alguma delas já estiver paga, esse pagamento é confirmado em vez de se cobrar um segundo. Se o eWAY não puder ser consultado sobre elas, o cliente vê We could not check the status of your previous payment attempt. Please try again in a moment. Se o eWAY não conseguir criar a página de pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem, por exemplo Payment error: Unable to connect to eWAY. Please try again. ou eWAY could not start the payment, com os códigos de erro do eWAY.

No OpenCart 4, o pedido permanece no checkout até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado sem pagamento nesse meio-tempo (por exemplo, se você o cancelou), o cliente volta ao checkout com a mensagem Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., 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 com uma nova quantidade, a mensagem é Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. Um pedido pago nunca é mostrado como pago para um carrinho diferente.

As URLs de retorno e de cron também funcionam enquanto a loja está em modo de manutenção, porque o OpenCart 3 deixa passar as requisições das extensões de pagamento, e a extensão adiciona para elas uma ação de inicialização no OpenCart 4.

O eWAY não envia notificações de servidor para servidor para a Shared Page: o resultado é obtido quando o cliente retorna e pela URL de cron. A extensão não tem campos de cartão no seu site, nem cartões salvos ou assinaturas, nem autorização sem captura e captura posterior, e não avalia as pontuações de fraude Beagle (transações bloqueadas pelas regras antifraude do eWAY são recusadas pelo próprio eWAY).

Pedidos e reembolsos

Status do pedido

No status (missing order): o cliente foi enviado ao eWAY e não pagou, cancelou, o pagamento foi recusado, ou o resultado ainda não pôde ser obtido. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Order Status on Success (default Processing): o pagamento foi aprovado. Uma observação mostra o ID da transação do eWAY, o código de autorização, a resposta e o modo (sandbox ou produção).

eWAY payment on hold status (default Pending): o eWAY aprovou um valor ou uma moeda diferentes do pedido (por exemplo, Approved for partial amount), o pagamento foi aprovado depois que o cliente o cancelou na página do eWAY, ou foi aprovado para um pedido ao qual você já tinha atribuído um status, por exemplo Canceled. O valor efetivamente capturado pelo eWAY é registrado, e a observação explica isso. Verifique o pedido e depois atenda-o ou estorne o pagamento.

Refunded order status (default Refunded): o pagamento foi estornado integralmente pela extensão.

Se um segundo pagamento for aprovado para um pedido já pago, ou para outro pedido do mesmo carrinho, o pedido pago não é alterado. Uma observação pede que você estorne o duplicado no MyeWAY. Um pagamento aprovado para outra referência de fatura nunca é aplicado ao pedido.

As observações são entradas do History do pedido que o cliente não vê.

Aba VibeFox eWAY Payment Gateway

Em Sales > Orders, abra um pedido pago com o eWAY. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox eWAY Payment Gateway mostra o ID da eWAY transaction com o selo Sandbox ou Live, o Auth code, a Response do eWAY, a Invoice reference, o Status do pagamento, os valores Paid / refunded, o formulário de estorno, o histórico de estornos e as eWAY notes do pedido. A aba é exibida para os usuários que têm acesso à extensão.

Reembolsos

Na aba, informe o valor (o valor ainda não estornado já vem preenchido), opcionalmente um Reason (optional), e clique em Refund via eWAY. Confirme a pergunta Refund this amount through eWAY? This cannot be undone. Estornos totais e parciais são suportados. Você precisa da permissão para modificar a extensão (definida em System > Users > User Groups). Os estornos são feitos no valor e na moeda que o eWAY cobrou: por isso, depois de uma aprovação por valor parcial, você pode estornar até o que o cliente realmente pagou, e não o total do pedido. O estorno é enviado no ambiente em que o pagamento foi feito (sandbox ou produção), por isso a chave e a senha da API desse ambiente precisam estar preenchidas. Se o eWAY recusar o estorno, a aba mostra eWAY refund failed: com os códigos do eWAY, e nenhum estorno é registrado. Um estorno bem-sucedido é adicionado ao histórico de estornos e às observações, com o ID da transação de estorno do eWAY. Um estorno total coloca o pedido no status Refunded order status sem notificar o cliente e sem devolver os produtos ao estoque, como uma alteração manual de status. Um estorno parcial não muda o status. Os estornos ficam disponíveis depois que o eWAY aprova o pagamento.

Devoluções de produtos em Sales > Returns não devolvem dinheiro pelo eWAY. Os estornos feitos no MyeWAY não são sincronizados de volta com o OpenCart. Atualize o pedido manualmente, se necessário.

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 eWAY Payment Gateway é o primeiro bloco de Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > 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-eway 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 eWAY 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é-visualização não está disponível: a loja não enxerga o login do administrador, então, 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, e os estornos continuam funcionando.

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

eWAY does not appear at checkout: verifique se a licença está ativa, se Enable/Disable está ativado, se a chave e a senha da API do modo atual estão preenchidas (os campos de sandbox no modo sandbox, os campos de produção no modo de produção) e se a moeda do checkout é AUD, NZD, SGD, HKD ou MYR. A página de configurações mostra um aviso quando as credenciais estão ausentes. 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 cliente não voltou do eWAY, ou o eWAY não pôde ser consultado naquele momento. O eWAY não envia notificações para a Shared Page. Configure a URL de cron de Re-check of lost returns (cron): ela recupera o pagamento cerca de uma hora depois. Confira a transação no MyeWAY e veja o campo Log na página da extensão.

The cron URL answers Forbidden: o token na URL está incorreto. Copie a URL exatamente como a página de configurações a mostra.

The customer sees This payment method is temporarily unavailable: faltam a chave ou a senha da API do modo atual, ou o eWAY as recusou. Verifique as credenciais do modo atual.

The customer sees eWAY could not start the payment: o eWAY devolveu códigos de erro, exibidos na mensagem. Muitas vezes, os dados de cobrança são inválidos.

The customer sees eWAY cannot take payments in a currency: a moeda do pedido não é uma das aceitas pelo eWAY. Use AUD, NZD, SGD, HKD ou MYR.

The customer sees We could not match this payment to an order: o link de retorno não pertence a um pedido desta loja, ou o eWAY aprovou um pagamento para outra referência de fatura. Se o cliente foi cobrado, localize o pagamento no MyeWAY.

The customer sees This payment method is not available: a sessão do checkout não corresponde mais ao pedido, ou o método de pagamento foi desativado nesse meio-tempo. O cliente recarrega o checkout.

Order is in the on hold status after payment: leia as eWAY notes na aba VibeFox eWAY Payment Gateway (veja Status do pedido) e depois atenda o pedido ou estorne o pagamento.

No refund form in the tab: a aba informa o motivo: não foi encontrado nenhum ID de transação do eWAY para o pedido, ele está totalmente estornado, seu grupo de usuários não tem permissão para modificar a extensão, ou as credenciais da API do modo do pagamento não estão preenchidas.

Refund fails with a message about the sandbox or live mode: o pedido foi pago nesse ambiente, e a chave e a senha da API dele não estão preenchidas. Informe-as e tente novamente.

Refund fails with at most … can be refunded: o valor é maior do que o eWAY cobrou, menos os estornos já feitos.

Para desenvolvedores: a extensão dispara os eventos do OpenCart wcp_eway_payment_gateway_supported_currencies (se a sua conta eWAY estiver habilitada para mais moedas) e wcp_eway_payment_gateway_create_access_code_request (o corpo da requisição antes de a página de pagamento ser criada).

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox eWAY Payment Gateway. 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. O evento do OpenCart da extensão também é removido (no OpenCart 4, também os seus eventos e a sua ação de inicialização, que deixa passar as URLs de retorno e de cron no modo de manutenção). Se Delete all plugin data on uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo sandbox, chaves e senhas da API, chave do log de depuração, token de cron) e o log são removidos. Se estiver desativado, eles são mantidos para uma reinstalação posterior. Os registros de pagamentos e estornos do eWAY são sempre mantidos, de modo que pedidos pagos antes ainda podem ser estornados depois de 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 e clique em Uninstall (o botão laranja −) ao lado de VibeFox eWAY Payment Gateway na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

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