VibeFox Mollie for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Moeda: a moeda da finalização de compra deve ser uma das moedas aceitas pela Mollie: AED, AUD, BGN, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, ISK, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TWD, USD, ZAR. Para outras moedas, o método de pagamento fica oculto na finalização de compra. Quais métodos de pagamento a Mollie oferece depende da moeda e da sua conta.

Acesso à internet para a sua loja: a Mollie envia webhooks para a sua loja, por isso o site precisa estar acessível pela internet. Sem os webhooks, os pedidos recebem o status quando o cliente retorna da Mollie.

Conta na Mollie: você precisa das chaves de API em Mollie Dashboard > Developers > API keys. As chaves de teste começam com test_, e as chaves de produção começam com live_. Não são necessárias outras chaves ou segredos. Os métodos de pagamento são ativados na sua conta da Mollie.

Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um 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 o README.txt, o pacote para o OpenCart 3 wcp_mollie_gateway-oc3-(version).ocmod.zip e o pacote para o OpenCart 4 wcp_mollie_gateway.ocmod.zip. Instale somente 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_mollie_gateway-oc3-(version).ocmod.zip. A extensão não possui modificações OCMOD, então 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. Encontre VibeFox Mollie Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa ter permissão para 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 License key).

4. Informe suas chaves de API de teste e de produção (veja Configuration). Não é preciso configurar nenhum webhook na Mollie.

5. Ative Enable/Disable e clique em Save. Mantenha Test Mode ativado até fazer um pagamento de teste e, depois, desative-o.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_mollie_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. Encontre VibeFox Mollie 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 e as chaves de API como nas etapas 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL do webhook é diferente (veja Webhook URL).

Uma nova instalação começa com o método de pagamento desativado e com o modo de teste ativado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Mollie Gateway > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa se a Mollie estiver ativada, mas a chave de API do modo atual estiver vazia, e se a Mollie não aceitar a moeda padrão da loja. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Sem a permissão para modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title precisa ter de 1 a 128 caracteres, Sort Order precisa ser um número inteiro e Total precisa ser um número igual ou maior que 0; caso contrário, nada é salvo. Uma chave de API que não comece com test_ ou live_, seguido de pelo menos 30 letras e números, não é salva: a página mostra Settings saved, except the API key shown in red., o erro indica a chave e a chave salva anteriormente é mantida.

Checkout

Enable/Disable: Enable Mollie Gateway ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o título do método de pagamento exibido ao cliente durante a finalização de compra. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Mollie. Obrigatório.

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

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

Geo Zone: oferece a Mollie somente 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 valor total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir para que a Mollie seja oferecida. Deixe em branco para oferecer a Mollie para qualquer valor.

Chaves de API

Encontre suas chaves de API no Mollie Dashboard, em Developers > API keys; a seção tem um link para essa página. As chaves de teste e de produção são separadas.

Test Mode: usa a chave de API de teste para os novos pagamentos. Nenhum pagamento real é processado. Na página de finalização de teste da Mollie, você pode escolher o resultado do pagamento. Os clientes veem Test mode: no real payment will be made. na etapa Confirm Order. Os pagamentos feitos no outro modo continuam usando a chave do próprio modo para verificação de status e reembolsos. Padrão: ativado.

Test API Key: sua chave de API de teste da Mollie (começa com test_).

Live API Key: sua chave de API de produção da Mollie (começa com live_).

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

Webhook

Webhook URL: exibido apenas como referência. Não é preciso configurar nenhum webhook: a extensão envia esta URL para a Mollie em cada pagamento. No OpenCart 3 ela tem a forma https://your-store/index.php?route=extension/payment/wcp_mollie_gateway/webhook, e no OpenCart 4, a forma https://your-store/index.php?route=extension/wcp_mollie_gateway/payment/wcp_mollie_gateway.webhook. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Ela precisa estar acessível pela internet; caso contrário, os pedidos recebem o status somente quando o cliente retorna da Mollie.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a Mollie informa o pagamento. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status definido após um pagamento bem-sucedido. Padrão: Processando. Escolha Complete para marcar os pedidos pagos como concluídos.

Awaiting Mollie Payment Status: o cliente escolheu transferência bancária na página da Mollie; o pedido é marcado como pago automaticamente quando a Mollie recebe o dinheiro. Padrão: Pendente.

Mollie Payment On Hold Status: o pagamento precisa da sua análise (veja Order statuses). Padrão: Pendente, porque o OpenCart não tem um status Em espera. Você pode criar seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Payment Error Status: a transferência bancária aguardada ou o pagamento autorizado falhou, expirou ou foi cancelado. Padrão: Falhou.

Refunded Status: o pagamento foi totalmente reembolsado na página do pedido. Padrão: Reembolsado.

Avançado

Logging: grava as chamadas de API e os webhooks no arquivo molg_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Os erros são sempre registrados, mesmo quando esta opção está desativada. As chaves de API e os dados dos clientes nunca são 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, as configurações do gateway e o log são excluídos ao desinstalar a extensão. Os IDs de pagamento da Mollie armazenados nos pedidos (pagamentos e reembolsos) são sempre mantidos. Padrão: desativado.

Importar / Exportar

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

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

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Mollie). Na etapa Confirm Order, o cliente vê a sua descrição e a observação You will be redirected to Mollie to choose a payment method and pay. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria um pagamento na Mollie pelo total do pedido, na moeda do pedido (JPY e ISK sem casas decimais), com a descrição Order # e o número do pedido, e envia o cliente para a página de pagamento hospedada pela Mollie. Lá, o cliente escolhe um dos métodos de pagamento ativados na sua conta da Mollie e paga. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco de método de pagamento, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização de compra.

Os webhooks da Mollie não têm assinatura, apenas o ID do pagamento. Por isso, a extensão nunca confia em um webhook por si só: ela aceita apenas IDs de pagamento que ela mesma criou, lê o pagamento pela API da Mollie com a chave do modo em que o pagamento foi feito, verifica se o pagamento pertence ao pedido e compara o valor e a moeda pagos com o total do pedido. O pedido só é marcado como pago depois que a Mollie confirma dessa forma. A extensão trata estes status de pagamento da Mollie:

Quando o cliente retorna, a extensão verifica o pagamento com a API da Mollie da mesma forma. Em seguida, o pedido recebe o seu status da maneira padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart com Your payment with Mollie has been received. Para uma transferência bancária, a página mostra Your order will be processed as soon as Mollie receives your bank transfer. Se o pedido estiver em espera, a página mostra We are confirming your payment with Mollie. The order will be updated automatically — please do not pay again. Se um pagamento aguardado falhou, a página mostra Your Mollie payment was not completed. Please contact us about this order.

Se o pagamento foi cancelado, falhou, expirou ou não foi concluído, o cliente volta à finalização de compra com uma mensagem, por exemplo You cancelled the Mollie payment. You can try again or choose another payment method. ou The Mollie payment has expired. Please try again or choose another payment method. No OpenCart 4, essas mensagens aparecem acima da página de finalização de compra. O carrinho é mantido. Se a Mollie não puder ser contatada ou ainda não tiver decidido, uma página Payment confirmation pede ao cliente que não pague de novo e oferece um botão Check again; o webhook define o status do pedido assim que chega.

No OpenCart 3, um novo pedido é criado sempre que a etapa Confirm Order é exibida; no OpenCart 4, o mesmo pedido é mantido na finalização de compra e pago novamente com um novo pagamento da Mollie. Em ambos os casos, a extensão trata todos os pedidos de um mesmo carrinho como um único pagamento. Quando o cliente paga novamente, o pagamento ainda aberto na Mollie, no mesmo valor, é reaproveitado em vez de criar um segundo pagamento cobrável. Se o total mudou, o pagamento antigo em aberto é cancelado na Mollie, quando a Mollie permite. Se um pagamento antigo foi feito nesse meio-tempo, esse pagamento é confirmado e o cliente vai para a página de sucesso, sem novo pagamento.

No OpenCart 4, o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se esse pedido foi encerrado sem pagamento nesse meio-tempo (por exemplo, a transferência bancária expirou, ou você o cancelou ou reembolsou), o cliente volta à finalização de compra com a mensagem Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order., e o próximo Confirm Order paga um novo pedido. Um pedido do carrinho que foi pago e depois cancelado ou reembolsado não mantém mais o carrinho.

Se a Mollie não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão, por exemplo The payment provider could not be reached. Please try again in a moment., This payment method is temporarily unavailable. Please choose another payment method. (chave de API incorreta) ou Mollie cannot accept a payment of this amount or currency. Please choose another payment method. O motivo técnico é gravado no log.

O webhook também funciona enquanto a loja estiver em modo de manutenção, porque o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona para isso uma ação de inicialização, que também permite ao cliente retornar da Mollie.

O cliente escolhe o método da Mollie na página da Mollie, e não na sua finalização de compra. A extensão não oferece assinaturas ou pagamentos recorrentes, cartões salvos ou mandatos, campos de cartão no seu site, botões express de Apple Pay ou PayPal nem a Orders API. Por isso, os métodos que exigem itens do pedido (por exemplo, algumas variantes de Klarna, Billie ou in3) não são oferecidos pela Mollie para esses pagamentos. Os pagamentos autorizados são capturados ou cancelados no Mollie Dashboard, e não no OpenCart.

Pedidos e reembolsos

Status dos pedidos

Sem status (pedido ausente): o cliente foi enviado à Mollie e não pagou, ou a Mollie ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Order Status After Payment (padrão Processando): o pagamento foi confirmado. Uma observação mostra o pagamento da Mollie (tr_...), o método e o modo.

Awaiting Mollie Payment Status (padrão Pendente): o cliente escolheu transferência bancária na página da Mollie. O pedido passa para o status de pago quando a Mollie recebe o dinheiro.

Mollie Payment On Hold Status (padrão Pendente): um pagamento autorizado aguarda a captura, a Mollie informou um estorno por contestação, o valor ou a moeda pagos diferiram do pedido, um pagamento de teste foi feito enquanto a loja está em modo de produção (nenhum dinheiro foi recebido), ou o pagamento chegou depois que o pedido recebeu outro status (por exemplo, foi cancelado). A observação explica. Verifique o pagamento no Mollie Dashboard e, depois, processe o pedido ou reembolse o pagamento.

Payment Error Status (padrão Falhou): uma transferência bancária ou uma autorização de um pedido falhou, expirou ou foi cancelada.

Refunded Status (padrão Reembolsado): o pagamento foi totalmente reembolsado pela extensão.

O OpenCart notifica o cliente sobre essas mudanças de status da forma habitual. Se um segundo pagamento do mesmo carrinho for feito, o pedido não é alterado. Uma observação no pedido pago pede que você reembolse o pagamento em duplicidade no seu Mollie Dashboard.

As observações são entradas do History do pedido que o cliente não vê.

Aba VibeFox Mollie Gateway

Em Sales > Orders, abra um pedido pago com a Mollie. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Mollie Gateway mostra o ID do Mollie payment, com o rótulo Test mode para pagamentos de teste, o Method, o Status do pagamento, os valores Paid / refunded, o formulário de reembolso, o histórico de reembolsos (data, ID do reembolso, valor, modo, status na Mollie, motivo) e as Mollie notes do pedido. A aba é exibida para os usuários que têm acesso à extensão.

Reembolsos

Na aba VibeFox Mollie Gateway, informe o Amount (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional), e clique em Refund via Mollie. Confirme a pergunta Refund this amount through Mollie? This cannot be undone. São aceitos reembolsos totais e parciais. Você precisa da permissão para modificar a extensão (definida em System > Users > User Groups). Os reembolsos são feitos no valor e na moeda cobrados pela Mollie; por isso, após uma divergência de valor, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. O reembolso é enviado para o pagamento que de fato quitou o pedido, com a chave de API do modo em que foi feito, por isso essa chave precisa estar configurada. Se a Mollie recusar o reembolso ou o informar como falho ou cancelado, a aba mostra a mensagem e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às observações, com o ID do reembolso da Mollie. Um reembolso total define o pedido como Refunded Status sem notificar o cliente e sem devolver os produtos ao estoque, como uma mudança manual de status. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que a Mollie informa o pagamento como pago.

As devoluções de produtos em Sales > Returns não devolvem dinheiro pela Mollie. Os reembolsos criados no Mollie Dashboard não aparecem no pedido; um estorno por contestação adiciona uma observação.

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 Mollie Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Mollie 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 ficam a linha Product: opencart-payment-mollie e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Apenas usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do 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 domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a Mollie 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 que esteja conectado ao administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado com (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évia não está disponível: a loja não enxerga o login no administrativo, por isso, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, aparece um lembrete no Dashboard do administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.

Quando uma licença expira, a extensão continua funcionando, mas as atualizações e o suporte exigem renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Não é necessário nenhum cron job. Ao desinstalar a extensão, a chave de licença e o status da licença são sempre removidos.

Solução de problemas

A Mollie não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o modo atual tem uma chave de API: Test API Key no modo de teste, Live API Key no modo de produção. Verifique se a moeda da finalização de compra é aceita pela Mollie, se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações. A página de configurações mostra um aviso para uma chave ausente e para uma moeda da loja não aceita.

O pagamento foi feito, mas o pedido continua sem status: o webhook não consegue chegar à sua loja. A URL exibida em Webhook URL precisa estar acessível pela internet (sem autenticação básica nem firewall bloqueando). O pedido também recebe o status quando o cliente volta à loja após pagar, ou quando o cliente clica em Check again.

O webhook responde Unknown payment.: o pagamento não foi criado por esta loja, ou a Mollie não o conhece com a chave de API do modo dele, por exemplo um pagamento de outra conta da Mollie.

O webhook responde Payment ID mismatch.: o pagamento não pertence ao pedido para o qual foi criado. Nada é alterado.

O webhook responde Failed to fetch payment.: a API da Mollie não pôde ser acessada, ou a chave de API do modo do pagamento não está definida. A Mollie tentará o webhook novamente mais tarde.

O webhook responde Temporarily unavailable.: o carrinho estava sendo processado por outra requisição no mesmo momento, ou o status do pedido não pôde ser definido. A Mollie tenta o webhook novamente. Ative Logging para ver o motivo.

A URL do webhook mostra Method not allowed. no navegador: isso é normal. A URL aceita apenas requisições da Mollie.

Uma chave de API não é salva: a chave deve começar com test_ ou live_, seguido de pelo menos 30 letras e números. Copie-a novamente do Mollie Dashboard.

O cliente vê um erro depois de Confirm Order: consulte o campo Log na página da extensão. Ele mostra o código HTTP e a mensagem da Mollie. 401 significa uma chave de API incorreta; 422 aponta para um campo da requisição, por exemplo um valor ou uma moeda que a Mollie não aceita. This payment method is not available. significa que a sessão de finalização de compra não corresponde mais ao pedido, ou que o método de pagamento foi desativado nesse meio-tempo: o cliente deve recarregar a finalização de compra.

O pedido está no status Em espera: leia as observações na aba VibeFox Mollie Gateway (veja Order statuses) e, depois, processe o pedido ou reembolse o pagamento.

Não há formulário de reembolso na aba: a aba informa o motivo: o pagamento ainda não foi feito, está totalmente reembolsado, o seu grupo de usuários não tem permissão para modificar a extensão, ou o pagamento foi feito no modo de teste ou de produção e a chave de API desse modo não está definida (informe-a e abra o pedido novamente).

Para desenvolvedores: a extensão dispara os eventos do OpenCart molg_supported_currencies (a lista de moedas) e molg_payment_data (a requisição de pagamento e o pedido, antes de o pagamento na Mollie ser criado).

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Mollie 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 valores padrão em uma nova instalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, seus eventos e sua ação de inicialização, que deixa o webhook passar no modo de manutenção). Se Delete Data on Uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo de teste, chaves de API, logging) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação posterior. Os IDs de pagamento da Mollie e os registros de reembolso são sempre mantidos, de modo que pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas observações de pagamento.

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

A Mollie é uma marca registrada do seu titular. Esta extensão não é afiliada à Mollie nem endossada por ela.