VibeFox EveryPay for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

Conta EveryPay: você precisa do nome de usuário da API, do segredo da API e do nome da conta de processamento da sua loja. Eles estão no Merchant Portal da EveryPay, nas configurações da sua loja: o portal de demonstração para o modo de teste e o portal de produção para pagamentos reais. Os ambientes de teste e de produção têm credenciais separadas. Você também configura a URL de callback da sua loja nos dois portais (veja Configuração).

Moeda da loja: a conta de processamento define a moeda cobrada; por exemplo, EUR3D1 cobra em EUR. O método de pagamento só é oferecido para carrinhos nessa moeda.

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. Quando o envio terminar, clique em Configure, ou encontre depois o VibeFox EveryPay Payment na lista de módulos e clique em Configure.

3. Insira 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 o nome de usuário da API de teste, o segredo da API de teste e o nome da conta de processamento do Merchant Portal de demonstração. Mantenha Test Mode ativado.

5. Copie a URL de callback exibida na página de configurações para o campo Callback notification URL da sua loja no Merchant Portal.

6. Ative Enable/Disable, clique em Save e faça um pedido de teste. Quando tudo estiver funcionando, insira as credenciais de produção, configure também a URL de callback no portal de produção e desative Test Mode.

Na instalação, o módulo cria o status de pedido EveryPay 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 EveryPay Payment > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra Modo de teste ativado: os pagamentos são enviados ao ambiente de demonstração da EveryPay, nenhum dinheiro real é cobrado. enquanto o modo de teste estiver ativo. Ela avisa quando o método de pagamento está ativado, mas faltam o nome de usuário da API, o segredo da API ou a conta de processamento do modo atual (nesse caso o método de pagamento fica oculto no checkout), e quando a conta de processamento cobra em outra moeda que não a moeda padrão da loja. Espaços e quebras de linha colados junto com as credenciais são removidos ao salvar.

EveryPay

Enable/Disable: Enable EveryPay payment gateway ativa ou desativa o método de pagamento. Padrão: off.

Title: o nome do método de pagamento que os clientes veem na finalização da compra. Também é o nome do método de pagamento salvo no pedido. Padrão: EveryPay.

Description: o texto exibido abaixo do método de pagamento na finalização da compra. Padrão: Pay securely by card or bank link on the EveryPay payment page.

Conta EveryPay

O nome de usuário da API, o segredo da API e o nome da conta de processamento são exibidos no Merchant Portal da EveryPay (configurações da loja): o portal de demonstração para o modo de teste e o portal de produção para pagamentos reais. A seção tem links para os dois portais.

Test Mode: quando ativado, os pagamentos são enviados ao ambiente de demonstração da EveryPay com as credenciais de teste. Nenhum dinheiro real é cobrado. Padrão: on. Enquanto estiver ativado, os clientes veem MODO DE TESTE: ambiente de demonstração da EveryPay, nenhum dinheiro real é cobrado. abaixo do método de pagamento.

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

Test API Secret: o segredo 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 segredo da API do ambiente de produção.

Os segredos salvos nunca são exibidos novamente. O campo fica vazio e mostra Salvo — deixe vazio para mantê-lo. Digite um novo valor somente se quiser alterá-lo.

Clear saved API secrets: marque um segredo e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

Processing Account Name: a conta de processamento da EveryPay, por exemplo EUR3D1. A conta define a moeda cobrada: o método de pagamento só é oferecido para carrinhos nessa moeda. O mesmo nome de conta é usado nos dois modos.

Notificações de pagamento (callback)

O callback informa à sua loja que um pagamento foi concluído, para que os pedidos sejam criados mesmo se o cliente fechar o navegador. Copie a URL exibida em Callback notification URL para o campo Callback notification URL da sua loja no Merchant Portal da EveryPay, tanto na demonstração quanto na produção. Com URLs amigáveis, ela fica assim: https://your-shop/module/wcp_everypay_payment/callback. Copie a URL exatamente como aparece nas configurações. A solicitação de pagamento não carrega uma URL de callback, por isso ela precisa ser definida no portal.

O callback traz apenas referências de pagamento. Quando ele chega, o módulo consulta a API da EveryPay sobre o status do pagamento com as credenciais do ambiente em que o pagamento foi criado e verifica se a resposta pertence a este carrinho. Callbacks de um pagamento que sua loja não criou são rejeitados sem nenhuma solicitação à EveryPay. Sem o callback, o pedido é criado quando o cliente volta à loja depois de pagar, ou quando a EveryPay repete o callback.

Avançado

Debug log: registra os eventos de pagamento em logs/wc_evp_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados, mesmo quando a opção está desativada. Segredos da API, dados de cartão e e-mails dos clientes nunca são registrados. Padrão: off.

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

Uninstall: remove as configurações do gateway e os logs quando o módulo é desinstalado. Os dados de pagamento da EveryPay dos pedidos são sempre mantidos. Padrão: off.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão EveryPay) e confirma. O módulo cria um pagamento único da EveryPay pelo valor total do carrinho, na moeda do carrinho, com o e-mail e o endereço de cobrança do cliente, e envia o cliente à página de pagamento da EveryPay. O idioma dessa página acompanha o idioma da loja (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. Neste ponto, ainda não existe pedido.

Depois do pagamento, o cliente volta à sua loja. O pedido só é marcado como pago depois que a EveryPay confirma: o módulo consulta a API da EveryPay sobre o status do pagamento no retorno e no callback. Em seguida, o pedido é criado e o cliente vê a página padrão de confirmação do pedido. Se a EveryPay ainda estiver processando o pagamento, ou se a API dela não puder ser acessada naquele momento, aparece uma página Payment confirmation com a mensagem Seu pagamento está sendo confirmado pela EveryPay. Você receberá um e-mail assim que o pedido for confirmado. e um botão Check again; o callback cria o pedido assim que a EveryPay confirma o pagamento.

Se o pagamento falhou, o cliente volta à finalização da compra com a mensagem Seu pagamento pela EveryPay não foi bem-sucedido. Tente novamente ou escolha outro método de pagamento. Se o cliente saiu da página de pagamento sem pagar, a mensagem é O pagamento pela EveryPay não foi concluído. Você pode tentar novamente ou escolher outro método de pagamento. O carrinho é mantido. Cada nova tentativa cria um novo pagamento da EveryPay; tentativas anteriores são reconhecidas, então um pagamento feito por um link antigo continua sendo reconhecido.

Se a EveryPay não conseguir iniciar o pagamento, o cliente permanece na finalização da compra com uma mensagem curta, por exemplo A EveryPay está temporariamente indisponível. Tente novamente em instantes ou escolha outro método de pagamento. Os detalhes estão no log.

O callback funciona mesmo quando a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.

O módulo aceita apenas pagamentos únicos. Não há reembolsos nem capturas pelo PrestaShop, cartões salvos ou pagamentos com um clique, assinaturas ou pagamentos recorrentes, campos de cartão incorporados e nem múltiplas moedas.

Pedidos

Status do pedido

No order yet: o cliente foi enviado à EveryPay e não pagou, o pagamento falhou ou foi abandonado, ou a EveryPay ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted: a EveryPay informou que o pagamento foi liquidado ou autorizado. O pagamento é registrado com a referência de pagamento da EveryPay como ID da transação, e uma nota mostra o valor, a moeda e a referência. Para um pagamento autorizado, a nota informa que os fundos estão reservados: se a sua conta não captura automaticamente, capture o pagamento no Merchant Portal da EveryPay. Quando ele for liquidado depois, uma nota informa isso.

EveryPay payment on hold: o pagamento precisa de revisão manual. O valor ou a moeda pagos diferem do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou), o pedido havia sido cancelado antes da chegada do pagamento, ou o pedido agora usa outro método de pagamento. A nota explica isso e informa que o pedido não foi marcado como pago. Verifique o pagamento no Merchant Portal e então processe ou reembolse manualmente. Callbacks posteriores desse pagamento não concluem o pedido automaticamente.

Se um segundo pagamento for concluído para um pedido que já está pago, o pedido não muda. Uma nota pede que você reembolse o pagamento duplicado no Merchant Portal da EveryPay.

Bloco de pagamento da EveryPay

A página do pedido mostra um bloco EveryPay payment com todas as tentativas de pagamento da EveryPay do pedido: data, referência do pagamento (com um selo Test mode para pagamentos de teste), referência do pedido, valor, status da EveryPay e resultado. Abaixo ficam as EveryPay notes do pedido, das mais recentes para as mais antigas.

Check EveryPay payment status: o botão do bloco verifica cada pagamento da EveryPay do pedido com a API, do mais recente para o mais antigo, aplica o resultado conforme descrito acima e adiciona uma nota com o status de cada pagamento. O resultado é exibido no bloco. Você precisa da permissão para editar pedidos; não é necessário acesso às páginas de Módulos. Use-o quando um callback nunca tiver chegado, por exemplo para ver uma captura ou um reembolso posterior.

Reembolsos

Reembolsos feitos pelo PrestaShop não são suportados. Faça o reembolso no Merchant Portal da EveryPay e depois atualize o status do pedido no PrestaShop. Quando a EveryPay informa que um pagamento foi reembolsado ou sofreu chargeback, o módulo apenas adiciona uma nota ao pedido; o status do pedido não é alterado. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela EveryPay.

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 EveryPay Payment é o primeiro bloco em Modules > Module Manager > VibeFox EveryPay Payment > 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-everypay 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, a EveryPay não é exibida aos clientes na finalização da 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 a verificação de status funciona.

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

A EveryPay não aparece na finalização da compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o nome de usuário da API, o segredo da API e o Processing Account Name do modo atual estão preenchidos e se a moeda do carrinho é a moeda da conta de processamento. Nesses casos, a página de configurações exibe um aviso. 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 concluído, mas nenhum pedido foi criado: o callback não está funcionando. Verifique se a URL de callback das configurações está definida como Callback notification URL no Merchant Portal do modo que você usa (demonstração ou produção). O pedido também é criado quando o cliente volta à loja após pagar. Veja o campo Log na página do módulo: os erros são sempre registrados.

O callback responde Unknown payment, Unknown payment reference ou Payment does not belong to this order: o pagamento não foi criado por esta loja ou por este carrinho, ou a resposta da EveryPay não corresponde a ele. Nada é alterado.

O callback responde Not configured: faltam as credenciais do ambiente em que o pagamento foi criado, por exemplo um pagamento de teste depois que as credenciais de teste foram removidas. Insira-as novamente; a EveryPay repete o callback.

O callback responde Payment status unavailable, Busy, please retry ou Order could not be created: não foi possível acessar a API da EveryPay, outra solicitação estava criando o pedido ao mesmo tempo, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A EveryPay repete o callback. O motivo está no log.

O cliente vê “A EveryPay está temporariamente indisponível”: a EveryPay recusou as credenciais ou não pôde ser acessada. Verifique o nome de usuário e o segredo da API do modo atual.

O cliente vê “Este método de pagamento não oferece suporte à moeda do pedido”: a moeda do carrinho é diferente da moeda da conta de processamento.

O cliente permanece na página Payment confirmation: a EveryPay ainda não concluiu o pagamento. O pedido é criado pelo callback ou quando o cliente clica em Check again depois que a EveryPay confirma o pagamento.

O pedido está em EveryPay payment on hold: leia as EveryPay notes no bloco do pedido. O valor ou a moeda eram diferentes, ou o pedido havia sido cancelado antes da chegada do pagamento. Verifique o pagamento no Merchant Portal e então processe ou reembolse manualmente.

Para desenvolvedores, o README do módulo lista os hooks actionWcpEverypayOneoffRequest (alterar a solicitação de pagamento) e actionWcpEverypayLocale (alterar o idioma da página de pagamento).

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox EveryPay Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Uninstall (excluir as configurações do gateway e os logs) estiver ativado nas configurações, as configurações do gateway e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados de pagamento da EveryPay dos pedidos e o status de pedido EveryPay payment on hold são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

A EveryPay é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela EveryPay.