VibeFox Mollie for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Moeda da loja: a moeda do carrinho deve ser uma das moedas suportadas 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, a opção de pagamento fica oculta 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, então o site precisa estar acessível pela internet. Sem webhooks, os pedidos ainda são criados quando o cliente volta da Mollie.
Conta Mollie: você precisa das chaves de API em Mollie Dashboard > Developers > API keys. As chaves de teste começam com test_, as de produção com live_. Nenhuma outra chave ou segredo é necessário. Os métodos de pagamento são ativados na sua conta Mollie.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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 Mollie Gateway na lista de módulos e clique em Configure.
3. Informe a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Informe as suas chaves de API de teste e de produção (veja Configuração). 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 então desative-o.
Na instalação, o módulo cria dois status de pedido, Awaiting Mollie payment e Mollie 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 Mollie Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando a Mollie está ativada, mas a chave de API do modo atual está vazia, e quando a Mollie não suporta a moeda padrão da loja. Nos dois casos, a opção de pagamento fica oculta na finalização de compra.
Ao salvar, uma chave de API que não começa com test_ ou live_ seguido de pelo menos 30 letras e números não é salva: aparece um erro e a chave salva anteriormente é mantida.
Finalização de compra
Enable/Disable: Enable Mollie Gateway ativa ou desativa a opção de pagamento. Padrão: off.
Title: o título do método de pagamento exibido ao cliente na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Mollie. Obrigatório.
Description: a descrição do método de pagamento exibida ao cliente na finalização de compra. Padrão: Pay securely via Mollie.
Chaves de API
Você encontra as 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 checkout de teste da Mollie, você pode escolher o resultado do pagamento. Os clientes veem Test mode: no real payment will be made. abaixo da opção de pagamento. Pagamentos feitos no outro modo continuam usando a chave do próprio modo para consultas de status e reembolsos. Padrão: on.
Test API Key: a sua chave de API de teste da Mollie (começa com test_).
Live API Key: a 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 valor novo somente se quiser alterá-la.
Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Webhook: mostra a URL do webhook. Não é preciso configurar nada: o módulo envia essa URL para a Mollie com cada pagamento. Com URLs amigáveis, ela tem esta aparência: https://your-shop/module/wcp_mollie_gateway/webhook, possivelmente com um código de idioma. Ela precisa estar acessível pela internet; do contrário, os pedidos só são criados quando o cliente volta da Mollie.
Pedidos
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido. O status é definido em uma única etapa.
As transferências bancárias ficam em Awaiting Mollie payment. Pagamentos autorizados e divergências de valor ou moeda vão para Mollie payment on hold.
Avançado
Logging: grava chamadas de API e webhooks em logs/molg_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 com esta opção desativada. Chaves de API e dados de 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.
Delete Data on Uninstall: quando ativado, as configurações do módulo e o seu log são excluídos ao desinstalar o módulo. Os IDs de pagamento da Mollie salvos nos pedidos, os registros de reembolso e os status de pedido do módulo são sempre mantidos. Padrão: off.
Finalização de compra
Na etapa de pagamento, o cliente escolhe a opção de pagamento (por padrão Mollie) e confirma. O módulo cria um pagamento na Mollie pelo total do carrinho na moeda do carrinho (JPY e ISK sem casas decimais), com a descrição Order # e o número do carrinho, e envia o cliente à página de checkout hospedada pela Mollie. Lá, o cliente escolhe um dos métodos ativados na sua conta Mollie e paga. Neste momento, ainda não existe pedido.
Os webhooks da Mollie não têm assinatura, apenas o ID do pagamento. Por isso, o módulo nunca confia em um webhook por si só: ele aceita apenas IDs de pagamento que ele mesmo criou, lê o pagamento na API da Mollie com a chave do modo em que o pagamento foi feito, confere se o pagamento pertence ao carrinho e compara o valor e a moeda pagos com o total do carrinho. O pedido só é marcado como pago depois que a Mollie confirma dessa forma. O módulo trata estes status de pagamento da Mollie:
Quando o cliente volta, o módulo confere da mesma forma o último pagamento do carrinho na API da Mollie. Um pagamento feito leva à página padrão de confirmação do pedido 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 o pagamento de um pedido existente falhou ou o pedido foi cancelado, 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. O carrinho é mantido. Se a Mollie não puder ser acessada ou ainda não tiver decidido, aparece uma página Payment confirmation que pede ao cliente que não pague de novo e oferece um botão Check again; o webhook cria o pedido assim que chegar.
Quando o cliente paga de novo, o pagamento da Mollie ainda aberto, do mesmo valor, é reutilizado em vez de criar um segundo pagamento pagável. Se o total do carrinho mudou, o pagamento aberto antigo é cancelado na Mollie quando a Mollie permite. Se o pagamento antigo foi pago nesse meio tempo, o pedido é criado sem um novo pagamento.
Se a Mollie não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma breve mensagem, 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 funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
O cliente escolhe o método Mollie na página da Mollie, não na finalização de compra da sua loja. O módulo não tem assinaturas nem pagamentos recorrentes, cartões salvos ou mandatos, campos de cartão no seu site, botões express de Apple Pay ou PayPal e nenhuma Orders API; por isso, a Mollie não oferece, para estes pagamentos, os métodos que precisam de linhas de pedido (por exemplo, algumas variantes de Klarna, Billie ou in3). Pagamentos autorizados são capturados ou anulados no Mollie Dashboard, não a partir do PrestaShop.
Pedidos e reembolsos
Status do pedido
Nenhum pedido ainda: o cliente foi enviado à Mollie e não pagou, ou a Mollie ainda não confirmou o pagamento. Existe apenas o carrinho.
Payment accepted ou Delivered: o pagamento foi confirmado. O status segue Order Status After Payment. O pagamento é registrado com o ID de pagamento da Mollie (tr_...) como ID da transação, e uma nota mostra o pagamento da Mollie, o método e o modo.
Awaiting Mollie payment: o cliente escolheu transferência bancária na página da Mollie. O pedido passa ao status pago quando a Mollie recebe o dinheiro.
Mollie payment on hold: um pagamento autorizado aguarda a captura, a Mollie informou um chargeback, o valor ou a moeda pagos diferiram do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou), um pagamento de teste foi feito com a loja em modo de produção (nenhum dinheiro foi recebido), ou o pagamento chegou depois que o pedido havia sido cancelado. A nota explica o motivo. Confira o pagamento no Mollie Dashboard e depois processe o pedido ou reembolse o pagamento.
Payment error: uma transferência bancária ou autorização de um pedido existente falhou, expirou ou foi cancelada. Um pedido pago nunca é alterado.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se um segundo pagamento do mesmo carrinho for feito, o pedido não muda. Uma nota pede que você reembolse o pagamento duplicado no seu Mollie Dashboard.
Bloco Mollie payment
A página do pedido mostra um bloco Mollie payment com o ID do pagamento da Mollie, o método, o status do pagamento, o valor pago e reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as Mollie notes do pedido. As notas são visíveis apenas no back office.
Reembolsos
No bloco Mollie payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Mollie. Confirme a pergunta Refund this amount through Mollie? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa da permissão para editar pedidos; o acesso às páginas de módulos não é necessário. Os reembolsos são feitos no valor e na moeda que a Mollie cobrou, então, após uma divergência de valor, você pode reembolsar até o montante que o cliente realmente pagou, e não o total do pedido. O reembolso é enviado para o pagamento que efetivamente 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, o bloco mostra a mensagem de erro da Mollie e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso da Mollie. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que a Mollie informa o pagamento como pago.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Mollie. Reembolsos criados no Mollie Dashboard não aparecem no pedido; um chargeback adiciona uma nota.
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 Mollie Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Mollie Gateway > 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 ficam a linha Product: presta-payment-mollie 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 com 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 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 na sua conta vibefox.net.
Sem uma chave ativa, a Mollie não é exibida aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, o cliente vê This payment method is not available. Please choose another one. 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ê: 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. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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. 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 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 do carrinho é suportada pela Mollie. A página de configurações mostra um aviso para uma chave ausente e para uma moeda da loja não suportada. 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 feito, mas nenhum pedido foi criado: o webhook não consegue chegar à sua loja. A URL exibida em Webhook precisa estar acessível pela internet (sem autenticação básica ou firewall bloqueando). O pedido também é criado quando o cliente volta à loja depois de pagar, ou quando 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 seu modo, por exemplo um pagamento de outra conta Mollie.
O webhook responde Payment ID mismatch.: o pagamento não pertence ao carrinho 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 tenta o webhook novamente mais tarde.
O webhook responde Temporarily unavailable.: o carrinho estava sendo processado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). 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 precisa 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 ao escolher a Mollie: veja o campo Log na página do módulo. Ele mostra o código HTTP e a mensagem da Mollie. 401 significa uma chave de API incorreta; 422 indica um campo da requisição, por exemplo um valor ou uma moeda que a Mollie não aceita.
O pedido está em Mollie payment on hold: leia as notas do pedido (veja Status do pedido) e depois processe o pedido ou reembolse o pagamento.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito em modo de teste ou de produção, e a chave de API desse modo não está definida. Informe-a e tente novamente.
Outras moedas ou dados de pagamento: desenvolvedores podem alterar a lista de moedas com o hook actionWcpMollieSupportedCurrencies e a requisição de pagamento com o hook actionWcpMolliePaymentData.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Mollie Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete Data on Uninstall estiver ativado, as configurações do módulo e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação futura. Os IDs de pagamento e os registros de reembolso da Mollie e os status de pedido Awaiting Mollie payment e Mollie payment on hold são sempre mantidos, para que pedidos pagos antes ainda possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e os IDs de transação.
Mollie é uma marca registrada do seu respectivo titular. Este módulo não é afiliado nem endossado pela Mollie.