VibeFox Eupago for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

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

Moeda: euro (EUR). A Eupago cobra apenas em euros, então, para carrinhos em outras moedas, o método de pagamento fica oculto na finalização de compra.

Conta na Eupago: você precisa da chave de API do seu canal da Eupago e da chave de um Webhook 2.0 que você cria no backoffice da Eupago (veja Configuração). O backoffice de produção é clientes.eupago.pt, o backoffice de sandbox é sandbox.eupago.pt. Sandbox e produção são contas separadas, com chaves separadas.

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

Instalação

1. No back office, acesse 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 o VibeFox Eupago Gateway depois na lista de módulos e clique em Configure.

3. Informe 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. Informe a chave de API do seu canal da Eupago, crie um Webhook 2.0 no backoffice da Eupago e cole a chave dele (veja Configuração).

5. Escolha o Payment Method, ative Enable/Disable e clique em Save. Faça um pedido de teste no modo sandbox e depois desative o Sandbox Mode.

Ao ser instalado, o módulo cria dois status de pedido: Awaiting Eupago payment e Eupago 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; o euro precisa continuar permitido para o módulo.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Eupago Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Quando o método de pagamento está ativado, a página avisa acima dos campos se a chave de API do modo atual estiver vazia (o método de pagamento fica então oculto na finalização de compra), ou mostra Sandbox mode: no real payments are taken. enquanto o modo sandbox estiver ligado.

Eupago

Enable/Disable: Enable Eupago Gateway liga ou desliga 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. Ele também é o nome do método de pagamento gravado no pedido. Padrão: Eupago. Obrigatório: um título vazio mostra Enter a title for the payment method.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Eupago.

Payment Method: o único método da Eupago oferecido na finalização de compra.

Order Status After Payment: o status do pedido definido quando o pagamento é confirmado.

Conta na Eupago

Obtenha a chave de API do seu canal e a chave do Webhook 2.0 no backoffice da Eupago: clientes.eupago.pt (produção) ou sandbox.eupago.pt (sandbox). Sandbox e produção são contas separadas, com chaves separadas.

Sandbox Mode: usa sandbox.eupago.pt e as chaves de sandbox. Nenhum pagamento real é cobrado. Padrão: ativado. Desative para receber pagamentos reais com as chaves de produção. Enquanto estiver ativado, os clientes veem SANDBOX / TEST MODE abaixo do método de pagamento.

Live API Key: a chave de API do seu canal da Eupago em produção (clientes.eupago.pt).

Live Webhook Key: a chave de criptografia do seu Webhook 2.0 de produção. Obrigatória: notificações sem assinatura válida são rejeitadas.

Sandbox API Key: a chave de API do seu canal de sandbox (sandbox.eupago.pt).

Sandbox Webhook Key: a chave de criptografia do seu Webhook 2.0 de sandbox.

As chaves salvas nunca são mostradas de novo. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-lo.

Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

URL do webhook

O webhook informa à sua loja que um pagamento foi feito. No backoffice da Eupago, crie um Webhook 2.0 com a URL mostrada nesta seção, método POST e criptografia ativada. Com URLs amigáveis ela fica assim: https://your-shop/module/wcp_eupago_gateway/webhook, possivelmente com um código de idioma como /pt/. Copie a URL exatamente como as configurações a mostram. Crie um webhook no backoffice de sandbox e outro no backoffice de produção.

Copie a chave de cada webhook para Sandbox Webhook Key ou Live Webhook Key. Webhooks sem assinatura válida são rejeitados. Um webhook sem criptografia só é aceito se a Eupago o assinar, por isso mantenha a criptografia ativada. Uma notificação precisa ser assinada com a chave do modo em que o pagamento foi iniciado, então uma notificação de sandbox nunca paga um pagamento de produção. O módulo reage a estes status de notificação:

Os demais status não exigem ação. O callback GET legado da Eupago para a mesma URL também é aceito; ele é autenticado pela chave de API e sempre informa um pagamento. Sem notificações, os pedidos nunca são marcados como pagos: o módulo não consulta a Eupago, e o retorno do cliente não paga um pedido. O webhook funciona com a loja em modo de manutenção e não é bloqueado pela restrição de países da sua loja.

Avançado

Debug Log: grava as chamadas de API e as notificações em logs/eupago_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves, e-mails e números de telefone completos não são registrados. Erros são sempre registrados. Padrão: desativado.

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

Delete Data on Uninstall: quando ativado, desinstalar o módulo remove as configurações do gateway, os registros de pagamento da Eupago deste módulo e o log. Os pedidos e os dados de pagamento deles são mantidos. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão, Eupago) na etapa de pagamento e faz o pedido. O que acontece depois depende do Payment Method.

Multibanco: na finalização de compra, o cliente vê You will receive Multibanco payment details after placing the order. O módulo cria uma referência Multibanco para o total do carrinho. O pedido é criado na hora em Awaiting Eupago payment, como qualquer pedido do PrestaShop, e o carrinho é esvaziado. A página de confirmação do pedido mostra Multibanco Payment Details com a entidade, a referência e o valor. Os mesmos dados são incluídos na linha de pagamento do e-mail de confirmação do pedido. O cliente paga em um caixa eletrônico ou no internet banking.

MB WAY: na finalização de compra, o cliente informa o MB WAY Phone Number, preenchido com o telefone do endereço de cobrança. Números portugueses podem ser informados sem +351. Um número incorreto mostra Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). O módulo envia a solicitação de pagamento ao aplicativo MB WAY e cria o pedido em Awaiting Eupago payment. A página de confirmação do pedido pede ao cliente que abra o aplicativo MB WAY no número mascarado e aprove a solicitação em até 5 minutos.

Credit Card: na finalização de compra, o cliente vê You will be redirected to a secure payment page to enter your card details. O cliente é enviado para a página de cartões da Eupago, em português, espanhol ou inglês conforme o idioma do carrinho. Ainda não existe pedido, e o carrinho é mantido. O pedido só é criado quando a Eupago confirma o pagamento. Se a notificação já tiver chegado quando o cliente voltar, ele vê a página padrão de confirmação do pedido. Caso contrário, uma página Payment confirmation mostra Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. com um botão Check again. Se o pagamento com cartão falhar ou for abandonado, o cliente volta à finalização de compra com The card payment was not completed. You can try again or choose another payment method. ou The card payment was cancelled. You can try again or choose another payment method.

Em todos os métodos, o pedido só é marcado como pago depois que a Eupago confirma o pagamento por meio de uma notificação verificada. Os detalhes de pagamento só são mostrados enquanto o pedido estiver em Awaiting Eupago payment. Se a Eupago informar depois que o pagamento foi cancelado, expirou ou falhou, e o pedido não estava pago, a página de confirmação do pedido mostra Your Eupago payment was not completed. Please contact us about this order.

Se a Eupago não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. Nenhum pedido é criado, e os detalhes ficam no log. Um carrinho em outra moeda mostra Eupago only supports payments in EUR.

O módulo oferece um método da Eupago por instalação. Não há reembolsos pelo PrestaShop, cartões salvos, assinaturas ou pré-autorização, nem PayShop, Cofidis Pay, Bizum ou outros métodos da Eupago, nem lembretes por SMS, data de expiração do Multibanco ou consulta de status.

Pedidos

Status do pedido

No order yet: um pagamento com cartão foi iniciado, e a Eupago ainda não o confirmou. Só existe o carrinho.

Awaiting Eupago payment: foi criada uma referência Multibanco ou uma solicitação MB WAY. A nota mostra a entidade e a referência, ou o número de telefone mascarado.

Payment accepted or Delivered: o pagamento foi confirmado. O status segue a Order Status After Payment. O pagamento é registrado com o ID de transação da Eupago como ID de transação, e uma nota mostra o método, o ID de transação e a referência.

Eupago payment on hold: a Eupago informou um pagamento com valor ou moeda diferentes, com uma referência que não foi criada para este carrinho, ou para um pedido que, nesse meio-tempo, foi cancelado ou falhou (por exemplo, uma referência Multibanco paga com atraso). A nota explica. Verifique o pagamento e o estoque e depois conclua o pedido manualmente ou reembolse o cliente. As notificações seguintes desse pagamento não concluem o pedido sem o seu conhecimento.

Canceled: a Eupago informou o pagamento como cancelado ou expirado, para a tentativa de pagamento atual de um pedido em espera.

Payment error: a Eupago informou um erro na tentativa de pagamento atual de um pedido em espera.

Se a Eupago informar outro pagamento para um pedido que já está pago (por exemplo, uma referência Multibanco anterior também foi paga), o pedido não muda. Uma nota pede que você verifique se há pagamento duplicado e o reembolse no backoffice da Eupago. Uma notificação de pagamento nunca reabre um pedido que foi pago e depois cancelado ou reembolsado.

Bloco de pagamento da Eupago

A página do pedido mostra um bloco Eupago payment com cada tentativa de pagamento do carrinho: data, método, um selo Sandbox para pagamentos de sandbox, valor, a entidade e a referência Multibanco ou o telefone mascarado do MB WAY, o ID de transação da Eupago e o status. Enquanto o pedido estiver em Eupago payment on hold, o bloco mostra um aviso Manual review. Abaixo, Eupago notes lista as notas do módulo sobre o pedido, das mais recentes para as mais antigas.

Reembolsos

Reembolsos pelo PrestaShop não são suportados. Reembolse o cliente no backoffice da Eupago e atualize o pedido no PrestaShop manualmente. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Eupago.

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 Eupago Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Eupago Gateway > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois, 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 deles estão a linha Product: presta-payment-eupago 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 do módulo podem alterar a chave. Os textos do bloco seguem o idioma do backoffice (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 Eupago 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. A loja do PrestaShop não sabe que você está conectado ao backoffice, então o método de pagamento também fica oculto para você: você pode configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado automaticamente de novo enquanto você trabalha no backoffice: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

A Eupago não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se a chave de API do modo atual está preenchida (Sandbox API Key no modo sandbox, Live API Key no modo de produção). A moeda do carrinho precisa ser EUR, e em Payment > Preferences o módulo precisa estar permitido para o euro, para o país do cliente e para o grupo do cliente. Com Multibanco, o total do pedido precisa estar entre 1 € e 999 999,99 €.

O pagamento foi feito, mas o pedido continua em Awaiting Eupago payment ou nenhum pedido foi criado: a notificação da Eupago não chega ou é rejeitada. No backoffice da Eupago do modo que você usa, verifique se o Webhook 2.0 existe, se a URL dele é exatamente a mostrada em Webhook URL, se o método é POST e se a criptografia está ativada. Verifique se a chave dele está no campo correspondente (Sandbox Webhook Key ou Live Webhook Key). Ative o Debug Log e veja o campo Log na página do módulo. Se uma notificação nunca chegar, verifique o pagamento no backoffice da Eupago.

O webhook responde Invalid signature ou Missing signature: a chave do webhook no módulo não corresponde à chave do webhook, ou o webhook não está criptografado nem assinado. Copie a chave novamente e mantenha a criptografia ativada.

O webhook responde Webhook key not configured: nenhuma chave de webhook está definida. A Eupago tenta a notificação novamente depois que você colar a chave.

O webhook responde Decryption failed: a assinatura é válida, mas não foi possível descriptografar o conteúdo. Verifique as configurações do Webhook 2.0 no backoffice da Eupago.

O webhook responde Environment mismatch: a notificação está assinada com a chave de outro modo, diferente do modo em que o pagamento foi iniciado. Uma notificação de sandbox nunca paga um pagamento de produção, e vice-versa. Verifique se as chaves de sandbox e de produção não foram trocadas.

O webhook responde Order not found: a notificação é de um carrinho sem pagamento Eupago desta loja, por exemplo um pagamento feito em outra loja com o mesmo canal da Eupago.

O webhook responde Busy or Retry: o carrinho estava sendo processado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Eupago tenta a notificação novamente. O motivo está no log.

O callback legado responde Invalid API key: a chave de API enviada pela Eupago não corresponde a Live API Key nem a Sandbox API Key. A mesma resposta aparece se você abrir a URL do webhook em um navegador; isso é normal.

O cliente vê The MB WAY payment could not be started: verifique se o número de telefone está associado ao MB WAY e tente novamente.

O pedido está em Eupago payment on hold depois do pagamento: leia as Eupago notes no bloco Eupago payment. O valor ou a moeda eram diferentes, a referência era desconhecida, ou o pagamento chegou depois que o pedido foi cancelado. Verifique o pagamento no backoffice da Eupago e depois conclua o pedido ou reembolse o cliente.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado do VibeFox Eupago Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se o Delete Data on Uninstall estiver ativado, as configurações do gateway, os registros de pagamento da Eupago deste módulo e o log são removidos. Se estiver desativado, todas as configurações e registros são mantidos para uma reinstalação posterior. Os status de pedido Awaiting Eupago payment e Eupago payment on hold são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

A Eupago é uma marca registrada de seu respectivo titular. Este módulo não é afiliado à Eupago nem endossado por ela.