VibeFox Eupago for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e posteriores (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: euro (EUR). A Eupago cobra apenas em euros, por isso o euro precisa estar habilitado na sua loja; quando o cliente paga em outra moeda, 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 criar 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: comprada em vibefox.net. Uma chave funciona em um único domínio.

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém README.txt, o pacote para OpenCart 3 wcp_eupago_gateway-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_eupago_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_eupago_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, portanto 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 Eupago Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa do direito de 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 de API do seu canal 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 Sandbox Mode.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_eupago_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do 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 Eupago 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 Eupago e o webhook como nos passos 3 a 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Somente a URL do webhook é diferente (veja URL do webhook).

Uma nova instalação 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 Eupago Gateway > Edit. As seções são listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Quando o método de pagamento está ativado, a página avisa acima das configurações 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 ativo. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, o título não pode estar vazio nem ter mais de 128 caracteres, um método de pagamento precisa ser escolhido, 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 precisam existir. Caso contrário, um erro indica o problema, por exemplo Enter a title for the payment method (1 to 128 characters)., e nada é salvo.

Eupago

Enable/Disable: Enable Eupago 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. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Eupago. Obrigatório, até 128 caracteres.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmar. Padrão: Pay securely via Eupago.

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

Sort Order: a posição da Eupago entre os métodos de pagamento na finalização de compra. Deixe vazio ou informe um número inteiro.

Geo Zone: oferece a Eupago apenas 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 da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir para que a Eupago seja oferecida. Deixe vazio para oferecer a Eupago em qualquer valor. Independentemente deste campo, a Eupago só é oferecida quando o cliente paga em EUR, e o Multibanco apenas para valores de 1 € a 999 999,99 €.

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 e produção são contas separadas, com chaves separadas.

Sandbox Mode: usa sandbox.eupago.pt e as chaves do 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 na etapa Confirm Order.

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.

As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo. Para remover uma chave salva, marque Clear the saved key on save abaixo do campo e clique em Save.

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 exibida nesta seção, método POST e criptografia ativada. No OpenCart 3 a URL tem a forma https://your-store/index.php?route=extension/payment/wcp_eupago_gateway/webhook, e no OpenCart 4 https://your-store/index.php?route=extension/wcp_eupago_gateway/payment/wcp_eupago_gateway.webhook. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Copie a URL exatamente como as configurações a mostram. Crie um webhook no backoffice 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 não criptografado 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, de modo que uma notificação de sandbox nunca paga um pagamento real. A extensão reage a estes status de notificação:

Outros status não exigem nenhuma 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: a extensão não consulta a Eupago, e o retorno do cliente não paga um pedido. O webhook também funciona enquanto a loja está em modo de manutenção, porque o OpenCart 3 libera as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização (startup action) para isso, inclusive para o retorno do cliente da página de cartão.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Com Multibanco e MB WAY, o pedido recebe o status de aguardando assim que a Eupago emite a referência ou a solicitação MB WAY. Com cartão, o pedido só recebe um status pela notificação da Eupago. O pedido só é marcado como pago quando chega uma notificação verificada e seu modo, referência, valor e moeda conferem com o pedido. Cada campo abaixo lista os seus status de pedido do OpenCart.

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

Awaiting payment status: a referência Multibanco ou a solicitação MB WAY foi emitida e o cliente ainda precisa pagar. Os dados do Multibanco são enviados com este status (no e-mail do pedido e no histórico de pedidos do cliente). Padrão: Pendente.

Manual review status: a Eupago informou um pagamento que não corresponde ao pedido (valor, moeda, referência), um pagamento posterior ao cancelamento do pedido, ou um pagamento de um pedido cujo carrinho já estava pago. Uma nota explica o motivo. Padrão: Pendente, porque o OpenCart não tem o status Em espera. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Cancelled status: a Eupago informou que o pagamento atual de um pedido em espera foi cancelado ou expirou. Padrão: Cancelado.

Failed status: a Eupago informou que o pagamento atual de um pedido em espera falhou (ERROR). Padrão: Falhou.

Avançado

Debug Log: grava as chamadas à API e as notificações em eupago_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 eupago_p_debug.old.log.php. Chaves, e-mails e números de telefone completos não são registrados. Os 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 Data on Uninstall: quando ativado, ao desinstalar a extensão são removidas as configurações do gateway e o log. Os pedidos e os registros de pagamento da Eupago deles são mantidos. Padrão: desativado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As chaves de API e de webhook não são exportadas.

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

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Eupago). O OpenCart cria o pedido na etapa Confirm Order, ainda sem status. No OpenCart 4 o cliente escolhe o método de pagamento com o botão Choose do bloco do método, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização de compra. O que acontece quando o cliente clica em Confirm Order depende de Payment Method.

Multibanco: o cliente vê You will receive Multibanco payment details after placing the order. A extensão cria uma referência Multibanco para o total do pedido em euros, e o pedido recebe Awaiting payment status. O e-mail do pedido e o histórico de pedidos do cliente recebem o comentário Multibanco Payment Details com a entidade, a referência e o valor. A página de sucesso do pedido mostra os mesmos dados. O cliente paga em um caixa eletrônico ou no internet banking.

MB WAY: o cliente informa o MB WAY Phone Number, preenchido com o telefone do pedido. Números portugueses podem ser digitados sem +351. No OpenCart 4 o telefone geralmente não é solicitado por padrão, então o campo costuma ficar vazio e o cliente informa o número. Um número incorreto mostra Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). A extensão envia a solicitação de pagamento ao aplicativo MB WAY, e o pedido recebe Awaiting payment status. A página de sucesso pede ao cliente que abra o aplicativo MB WAY no número de telefone mascarado e aprove a solicitação em até 5 minutos. Se a Eupago recusar a solicitação, o cliente permanece na etapa Confirm Order com The MB WAY payment could not be started. Check that the phone number is associated with MB WAY and try again.

Credit Card: 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ão da Eupago, em português, espanhol ou inglês conforme o idioma da loja. O pedido permanece sem status, e o carrinho é mantido. Se a notificação tiver chegado quando o cliente voltar, ele vê a página de sucesso do pedido do OpenCart. 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 os botões Check again e Back to checkout. 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. No OpenCart 4 essas mensagens são exibidas acima da página de finalização de compra.

Para todos os métodos, o pedido só é marcado como pago depois que a Eupago o confirma com uma notificação verificada. Em seguida, o pedido recebe o seu status da forma padrão do OpenCart, com a atualização do estoque. Os detalhes do pagamento só são exibidos na página de sucesso enquanto o pedido aguarda o pagamento. Se a Eupago já tiver informado que o pagamento foi cancelado, expirou ou falhou, a página de sucesso mostra Your Eupago payment was not completed. Please contact us about this order.

O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida. O OpenCart 4 atualiza o pedido da finalização de compra, então, após um pagamento com cartão cancelado ou não concluído, o cliente paga o mesmo pedido com um novo pagamento da Eupago. Se um pedido anterior do mesmo carrinho já estiver pago pela Eupago, o cliente vai para a página de sucesso e nenhum novo pagamento é criado.

O OpenCart 4 mantém o pedido na finalização de compra até que a página de sucesso seja exibida. Se, nesse meio tempo, esse pedido tiver sido encerrado sem pagamento (por exemplo, a referência Multibanco expirou, a solicitação MB WAY foi recusada ou você cancelou o pedido), o cliente volta à finalização de compra com 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 ou aguardando o pagamento, mas o carrinho tiver mudado desde então, inclusive com uma nova quantidade, a mensagem é Your previous order is already paid or awaiting its payment. Please confirm the order again: the cart will be paid with a new order. Um pedido pago nunca é mostrado como pago para um carrinho diferente.

Se a Eupago não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem, 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 fica sem status, e os detalhes são gravados no log.

A extensão oferece um método da Eupago por instalação. Não há reembolsos pela loja, cartões salvos, assinaturas ou pré-autorização, nem PayShop, Cofidis Pay, Bizum ou outros métodos da Eupago, nem lembretes por SMS, nem data de validade do Multibanco, nem consulta de status.

Pedidos

Status do pedido

No status (missing order): um pagamento com cartão foi iniciado e a Eupago ainda não o confirmou, ou ele falhou. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Awaiting payment status (default Pending): foi criada uma referência Multibanco ou uma solicitação MB WAY. A nota mostra a entidade e a referência ou o telefone mascarado.

Order Status After Payment (default Processing): o pagamento foi confirmado. Uma nota mostra o método, o ID de transação da Eupago e a referência.

Manual review status (default Pending): a Eupago informou um pagamento com valor ou moeda diferentes, com uma referência que não foi criada para este pedido, para um pedido que nesse meio tempo foi cancelado ou falhou (por exemplo, uma referência Multibanco paga com atraso), ou para um pedido cujo carrinho já havia sido pago por outro pedido. A nota explica isso. Confira o pagamento e o estoque e, depois, conclua o pedido manualmente ou reembolse o cliente. As notificações posteriores deste pagamento não concluem o pedido sem o seu conhecimento.

Cancelled status (default Canceled): a Eupago informou que o pagamento atual de um pedido em espera foi cancelado ou expirou.

Failed status (default Failed): 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. As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox Eupago Gateway

Em Sales > Orders, abra um pedido pago com a Eupago. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Eupago Gateway lista cada tentativa de pagamento do pedido: Date, Method (com um rótulo Sandbox nos pagamentos de sandbox), Amount, Entity / reference / phone, Eupago transaction ID e Status. Para um pedido em revisão manual, a aba mostra um aviso. Abaixo, Eupago notes lista as notas da extensão sobre o pedido. A aba é somente leitura e é exibida aos usuários que têm acesso à extensão.

Reembolsos

Reembolsos não estão disponíveis nesta extensão. Reembolse o cliente no backoffice da Eupago e atualize o pedido no OpenCart manualmente. Devoluções de produtos em Sales > Returns não devolvem dinheiro pela Eupago.

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 Eupago Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Eupago 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 novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo deles aparecem a linha Product: opencart-payment-eupago 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 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja definido na configuração do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em 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. Um usuário administrador conectado ao painel administrativo no mesmo navegador continua vendo 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 vê o login do painel administrativo, 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. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do painel: 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 a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

Eupago does not appear at checkout: verifique se a licença está ativa, se Enable/Disable está ativado e se a chave de API do modo atual está configurada (Sandbox API Key no modo sandbox, Live API Key no modo de produção). O cliente precisa pagar em EUR, e com Multibanco o valor do pedido deve estar entre 1 € e 999 999,99 €. 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 in the awaiting status or without a status: 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 exibida 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 da extensão. Se uma notificação nunca chegar, verifique o pagamento no backoffice da Eupago.

Webhook answers Invalid signature or Missing signature: a chave do webhook na extensão não corresponde à chave do webhook, ou o webhook não está criptografado nem assinado. Copie a chave novamente e mantenha a criptografia ativada.

Webhook answers Webhook key not configured: nenhuma chave de webhook está definida. A Eupago repete a notificação depois que você cola a chave.

Webhook answers Decryption failed: a assinatura é válida, mas o conteúdo não pôde ser descriptografado. Verifique as configurações do Webhook 2.0 no backoffice da Eupago.

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

Webhook answers Order not found: a notificação se refere a um pedido sem um pagamento da Eupago desta loja, por exemplo um pagamento feito em outra loja com o mesmo canal da Eupago.

Webhook answers Busy or Retry: o pedido estava sendo processado por outra requisição no mesmo momento, ou o processamento falhou. A Eupago repete a notificação. O motivo está no log.

Legacy callback answers 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.

The customer sees This payment method is temporarily unavailable: falta a chave de API do modo atual. Informe-a nas configurações.

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

Order is in the manual review status after payment: leia as Eupago notes na aba VibeFox Eupago Gateway. O valor ou a moeda eram diferentes, a referência era desconhecida, o pagamento chegou depois que o pedido foi cancelado ou o carrinho já estava pago por outro pedido. Verifique o pagamento no backoffice da Eupago e depois conclua o pedido ou reembolse o cliente.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Eupago 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 padrões em uma reinstalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, seus eventos e a sua ação de inicialização, que deixa o webhook e o retorno do cliente passarem no modo de manutenção). Se Delete Data on Uninstall estiver ativado, as demais configurações do gateway (título, descrição, método de pagamento, modo sandbox, chaves, log de depuração) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação posterior. Os registros de pagamento da Eupago dos pedidos são sempre mantidos, de modo que notificações tardias de pedidos antigos continuam funcionando após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Eupago Gateway na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Eupago é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Eupago.