VibeFox eWAY 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.
Moeda da loja: AUD, NZD, SGD, HKD ou MYR. Para outras moedas do carrinho, o método de pagamento fica oculto na finalização de compra. O pagamento é cobrado na moeda do carrinho.
Conta do eWAY: você precisa de uma conta de comerciante no eWAY com acesso à Rapid API e da respectiva chave e senha da Rapid API, obtidas no MyeWAY em Settings, API Key. Para testes, você precisa de uma conta sandbox do eWAY com chave e senha próprias. As chaves de sandbox e de produção são diferentes. Não é preciso configurar nada no eWAY: a URL de retorno é enviada em cada pagamento.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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. Ao concluir o envio, clique em Configure ou, depois, encontre VibeFox eWAY Payment Gateway na lista de módulos e clique em Configure.
3. Insira 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. Insira 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. Insira a chave e a senha da API de produção, desative Sandbox Mode e clique em Save.
6. Opcionalmente, adicione a URL de cron exibida na página Configure às tarefas cron do seu servidor (veja Configuração).
Na instalação, o módulo cria o status de pedido eWAY 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 eWAY Payment Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, um selo mostra 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 e a senha da API do modo atual não estão preenchidas (o método de pagamento não aparece na finalização de compra) e quando a moeda padrão da loja não é suportada pelo eWAY.
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ê na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit Card (eWAY). Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.
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.
Sandbox Mode: os pagamentos vão para o 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 ativado, o cliente verá Test mode: no real payment is taken. abaixo do método de pagamento.
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 do seu sandbox do eWAY (conta de parceiro/desenvolvedor).
Sandbox API Password: a senha da Rapid API da sua conta sandbox do 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.
Clear saved credentials: marque uma chave ou senha e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Return URL / re-checks: não é preciso configurar nenhum webhook nem URL de retorno no eWAY, porque a URL de retorno é enviada em cada pagamento. Este campo mostra uma URL de cron opcional. Chame-a a partir de uma tarefa cron do servidor, por exemplo a cada 15 minutos. Se um cliente pagar e fechar o navegador antes de voltar para a loja, o pagamento é consultado no eWAY cerca de uma hora depois e o pedido é criado. Se o eWAY não puder ser acessado, a verificação é repetida até três vezes. Mantenha esta URL em segredo: ela contém um token, e uma chamada com token incorreto recebe a resposta Forbidden.
Pedidos
Order Status on Success: o status do pedido depois que o eWAY confirma o pagamento.
Um valor ou uma moeda aprovados que não correspondam ao pedido sempre vão para eWAY payment on hold.
Avançado
Debug log: grava as chamadas à API e os resultados dos pagamentos em logs/eway_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Dados de cartão, chaves, senhas, e-mails dos clientes e códigos de acesso não são registrados. Erros são sempre registrados. Padrão: desativado.
Log: mostra o tamanho e as entradas mais recentes do registro. Clique em Clear log para esvaziá-lo.
Delete all plugin data on uninstall: quando ativado, desinstalar o módulo remove as configurações do gateway e o registro. Os dados de pagamento do eWAY nos pedidos e o status eWAY payment on hold são sempre mantidos. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Credit Card (eWAY)) e confirma. O módulo pede ao eWAY uma página de pagamento para o valor total do carrinho na moeda do carrinho, com PS- e o número do carrinho como referência da fatura, além do endereço de cobrança e do e-mail do cliente, e envia o cliente para a eWAY Responsive Shared Page. Ali o cliente paga com cartão. A cobrança é feita imediatamente. Neste ponto, ainda não existe nenhum pedido.
Depois do pagamento, o cliente volta para a sua loja. O módulo não confia no navegador: ele consulta o eWAY, de servidor para servidor, o resultado da página de pagamento criada para este carrinho. O pedido só é marcado como pago depois que o eWAY confirma e o valor e a moeda aprovados correspondem ao carrinho. Em seguida, o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your payment with eWAY has been received. Para um pedido em espera, a página mostra 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 é criado quando o cliente verifica novamente ou quando a URL de cron é executada.
Se o pagamento for recusado, o cliente volta à finalização de compra com o motivo, por exemplo Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. Se o cliente clicar em Cancel na página do eWAY, o módulo primeiro confere com o eWAY se 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.
O cliente pode tentar novamente. Antes de criar uma nova página de pagamento, a página anterior do carrinho é conferida no eWAY. Se ela já estiver paga, o pedido é criado em vez de um segundo pagamento. Se o eWAY não conseguir criar a página de pagamento, o cliente permanece na finalização de compra com uma mensagem curta, 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.
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. O módulo não tem campos de cartão no seu site, cartões salvos ou assinaturas, nem autorização sem captura e captura separada, e não avalia as pontuações antifraude Beagle (transações bloqueadas pelas regras antifraude do eWAY são recusadas pelo próprio eWAY).
Pedidos e reembolsos
Status do pedido
No order yet: 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. Apenas o carrinho existe.
Payment accepted or Delivered: o pagamento foi aprovado. O status segue Order Status on Success. O pagamento é registrado com o ID da transação do eWAY, e uma nota mostra o ID da transação, o código de autorização, a resposta e o modo (sandbox ou produção).
eWAY payment on hold: o eWAY aprovou um valor ou uma moeda diferentes do carrinho (por exemplo, Approved for partial amount, ou o carrinho foi alterado depois que o cliente abriu a página de pagamento), o pagamento foi aprovado depois que o cliente o cancelou na página do eWAY, ou foi aprovado depois que o pedido havia sido cancelado. O pagamento é registrado com o valor que o eWAY cobrou, e a nota explica o caso. Verifique o pedido e atenda-o ou reembolse o pagamento.
Refunded: o pagamento foi reembolsado integralmente pelo módulo.
Se um segundo pagamento for aprovado para um carrinho que já está pago, o pedido não muda. Uma nota pede que você reembolse a duplicata no MyeWAY. Um pagamento aprovado para outra referência de fatura nunca é aplicado ao pedido.
Bloco de pagamento do eWAY
A página do pedido mostra um bloco eWAY payment com o ID da transação, o código de autorização, a resposta do eWAY, o status, o modo e a referência da fatura, o valor pago e reembolsado, um selo Sandbox para pagamentos de sandbox, o histórico de reembolsos e as eWAY notes do pedido.
Reembolsos
No bloco eWAY payment, digite o valor (o valor ainda não reembolsado é preenchido automaticamente), opcionalmente um motivo, e clique em Refund via eWAY. Confirme a pergunta Refund this amount through eWAY? This cannot be undone. Há suporte a reembolsos totais e parciais. Você precisa da permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. Os reembolsos são feitos no valor e na moeda que o eWAY cobrou, então, depois de uma aprovação de valor parcial, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. O reembolso é 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 reembolso, o bloco mostra eWAY refund failed: com os códigos do eWAY, e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas com o ID da transação de reembolso do eWAY. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos estão disponíveis depois que o eWAY aprova o pagamento.
O módulo não cria notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pelo eWAY. Os reembolsos feitos no MyeWAY não são sincronizados com o PrestaShop. Atualize o pedido manualmente, se necessário.
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 eWAY Payment Gateway é o primeiro bloco em Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-payment-eway e o link Manage licenses and domains in your account, que abre a sua conta 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 seguido de 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, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, o eWAY não é exibido aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê Este método de pagamento não está disponível. Por favor, escolha outro. 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ê: é possível configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização da compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: os 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 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 inserção da chave e depois uma vez por semana. Nenhuma tarefa cron é necessária. Desinstalar ou redefinir o módulo 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 (campos de sandbox no modo sandbox, campos de produção no modo de produção) e se a moeda do carrinho é AUD, NZD, SGD, HKD ou MYR. A página de configurações mostra um aviso quando as credenciais estão ausentes. 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.
The payment went through, but no order was created: 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 Return URL / re-checks: ela recupera o pagamento cerca de uma hora depois. Verifique a transação no MyeWAY e consulte o campo Log na página do módulo.
The customer sees This payment method is temporarily unavailable: a chave ou a senha da API do modo atual estão ausentes, ou o eWAY as recusou. Verifique as credenciais do modo atual.
The customer sees eWAY could not start the payment: o eWAY retornou códigos de erro, exibidos na mensagem. Muitas vezes, os dados de cobrança estão inválidos.
The customer sees We could not match this payment to an order: o link de retorno não pertence a um carrinho desta loja, ou o eWAY aprovou um pagamento para outra referência de fatura. Se o cliente foi cobrado, procure o pagamento no MyeWAY.
The customer sees We could not check the status of your previous payment attempt: outra requisição estava processando o mesmo carrinho. O cliente pode tentar novamente em instantes.
Order is eWAY payment on hold after payment: leia as eWAY notes no bloco eWAY payment (veja Status do pedido) e, em seguida, atenda o pedido ou reembolse o pagamento.
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. Insira-as e tente novamente.
Refund fails with at most … can be refunded: o valor é maior do que o eWAY cobrou, menos os reembolsos já feitos.
Para desenvolvedores: o README do módulo lista o hook actionWcpEwaySupportedCurrencies, caso a sua conta do eWAY esteja habilitada para mais moedas.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox eWAY Payment Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete all plugin data on uninstall estiver ativado, as configurações do gateway e o registro são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados de pagamento do eWAY nos pedidos e o status eWAY payment on hold são sempre mantidos, então pedidos pagos anteriormente ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
O eWAY é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado ao eWAY nem endossado por ele.