VibeFox Eupago for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo.
PHP: 8.0 ou superior.
Moeda da loja: euro (EUR). A Eupago cobra somente em euros; por isso, para outras moedas, o método de pagamento fica oculto na finalização de compra.
Conta Eupago: você precisa da chave de API do seu canal 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 de sandbox é sandbox.eupago.pt. Sandbox e produção são contas separadas, com chaves separadas.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_eupago_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Eupago > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Informe sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Informe a chave de API do seu canal Eupago, crie um Webhook 2.0 no backoffice da Eupago e cole a chave dele (veja Configuração).
6. Escolha o Payment Method, ative Enable/Disable, faça um pedido de teste no modo sandbox e depois desmarque Sandbox Mode.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Eupago. Quando o gateway está ativado, a página avisa se a chave de API do modo atual está vazia (nesse caso o gateway fica oculto na finalização de compra), ou exibe Sandbox mode: no real payments are taken. enquanto o modo sandbox estiver ativo. Na lista de métodos de pagamento, a Eupago aparece marcada como precisando de ação até que a chave de API do modo atual seja definida, e exibe um selo de modo de teste no modo sandbox.
Geral
Enable/Disable: Enable Eupago 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 de compra. Padrão: Eupago.
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: Processing (padrão) ou Completed. O status é definido de imediato, com uma única mudança de status e um único e-mail.
Conta 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 Mode: Enable sandbox/test mode usa sandbox.eupago.pt e as chaves de sandbox. Nenhum pagamento real é cobrado. Padrão: on. Desmarque para cobrar pagamentos reais com as chaves de produção.
Live API Key: a chave de API do seu canal Eupago de 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 sandbox (sandbox.eupago.pt).
Sandbox Webhook Key: a chave de criptografia do seu Webhook 2.0 sandbox.
URL do webhook
O webhook avisa a sua loja de que um pagamento foi feito. No backoffice da Eupago, crie um Webhook 2.0 com a URL exibida nesta seção das configurações, método POST e criptografia ativada. A URL tem este formato: https://your-site/wc-api/eupago_payment_callback/. Crie um webhook no backoffice de sandbox e outro no 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, então mantenha a criptografia ativada. O plugin reage aos seguintes 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 plugin não consulta a Eupago, e o retorno do cliente não paga um pedido.
Avançado
Debug Log: Enable logging grava chamadas de API e notificações em WooCommerce > Status > Logs, origem wcp_eupago_gateway. Chaves, e-mails e números de telefone completos não são registrados. Erros são sempre registrados. Padrão: off.
Delete Data on Uninstall: Delete all plugin data when uninstalling. Se marcada, as configurações do gateway e os logs são removidos quando o plugin é excluído. Os pedidos e seus dados de pagamento são mantidos. Padrão: off.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Eupago) e faz o pedido. No modo sandbox, a finalização de compra exibe SANDBOX / TEST MODE. O que acontece em seguida depende de Payment Method.
Multibanco: na finalização de compra, o cliente vê You will receive Multibanco payment details after placing the order. O plugin cria uma referência Multibanco para o valor total do pedido. O pedido passa para o status Aguardando, o estoque é reduzido e o carrinho é esvaziado. A página de pedido recebido mostra Multibanco Payment Details com a entidade, a referência e o valor. Os mesmos dados são incluídos no e-mail do pedido enquanto ele aguarda pagamento. O cliente paga em um caixa eletrônico ou no internet banking.
MB WAY: na finalização de compra, o cliente informa MB WAY Phone Number, preenchido com o telefone de cobrança. Números portugueses podem ser informados sem +351. Um número incorreto exibe Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). O plugin envia a solicitação de pagamento para o aplicativo MB WAY. O pedido passa para o status Aguardando, o estoque é reduzido e o carrinho é esvaziado. A página de pedido recebido pede ao cliente que abra o aplicativo MB WAY 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 site. O pedido permanece em Aguardando pagamento e o carrinho é mantido. Depois de pagar, o cliente volta para a página de pedido recebido, que exibe Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. até a chegada da notificação. Se o pagamento com cartão falhar ou for abandonado, o cliente cai na página Pay for order 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 com uma notificação verificada. O cliente pode pagar novamente um pedido não pago pela página Pay for order; cada referência de pagamento criada para o pedido continua válida para a verificação.
Se a Eupago não conseguir iniciar o pagamento, o cliente vê 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. O pedido não muda, e os detalhes ficam no log.
O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS). Os textos exibidos ao cliente estão traduzidos para o português.
O plugin oferece um método Eupago por instalação. Não há reembolsos pelo WooCommerce, cartões salvos, assinaturas ou pré-autorização, nem PayShop, Cofidis Pay, Bizum ou outros métodos da Eupago, lembretes por SMS, data de expiração do Multibanco nem consulta de status.
Pedidos
Status do pedido
Pending payment: um pagamento com cartão foi iniciado e a Eupago ainda não o confirmou.
On hold, awaiting payment: foi criada uma referência Multibanco ou uma solicitação MB WAY. A nota do pedido mostra a entidade e a referência ou o número de telefone mascarado.
Processing or Completed: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra o método, o ID da transação na Eupago e a referência. O ID de transação do pedido é o ID de transação da Eupago.
On hold, manual review: a Eupago informou um pagamento com valor ou moeda diferentes, com uma referência que não foi criada para este pedido, ou para um pedido que, nesse meio-tempo, havia sido cancelado ou falhado (por exemplo, uma referência Multibanco paga com atraso). A nota explica isso. Verifique o pagamento e o estoque e, em seguida, conclua o pedido manualmente ou reembolse o cliente. Notificações posteriores desse pagamento não concluem o pedido sem o seu conhecimento.
Cancelled: a Eupago informou o pagamento como cancelado ou expirado, para a tentativa de pagamento atual de um pedido não pago.
Failed: a Eupago informou um erro na tentativa de pagamento atual de um pedido não pago.
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 é alterado. Uma nota pede que você verifique se há um 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.
Reembolsos: reembolsos pelo WooCommerce não são suportados. Reembolse o cliente no backoffice da Eupago e registre o reembolso no WooCommerce com Refund manually.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Eupago. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Eupago não é exibida 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. Os gerentes da loja conectados continuam vendo o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado de novo automaticamente em segundo plano.
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, se a chave de API do modo atual está definida (Sandbox API Key no modo sandbox, Live API Key no modo de produção) e se a moeda da loja é EUR. No Multibanco, o valor do pedido deve estar entre 1 € e 999 999,99 €.
O pagamento foi feito, mas o pedido continua Pending payment ou On hold: 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 é exatamente a exibida nas configurações, se o método é POST e se a criptografia está ativada. Confira se a chave dele está no campo correspondente (Sandbox Webhook Key ou Live Webhook Key). Ative o Debug Log e veja em WooCommerce > Status > Logs, origem wcp_eupago_gateway. 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 plugin não corresponde à chave do webhook, ou o webhook está sem criptografia e sem assinatura. Copie a chave novamente e mantenha a criptografia ativada.
O webhook responde Webhook key not configured: nenhuma das chaves de webhook está definida. A Eupago repete a notificação depois que você colar a chave.
O webhook responde Decryption failed: a assinatura é válida, mas o corpo não pôde ser descriptografado. 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 do outro modo, diferente do modo em que o pedido foi feito. Uma notificação de sandbox nunca paga um pedido de produção, e vice-versa.
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.
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á On hold após o pagamento: leia a nota do pedido. 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, em seguida, conclua o pedido ou reembolse o cliente.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Para desenvolvedores, a documentação do plugin lista os filtros eupago_p_icon (ícone da finalização de compra) e eupago_p_card_language (idioma da página de cartões da Eupago: PT, EN ou ES).
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações do gateway e os logs só são removidos se Delete Data on Uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos e as referências Eupago deles são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Eupago é uma marca de propriedade do respectivo titular. Este plugin não é afiliado nem endossado pela Eupago.