VibeFox Mollie for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. Sem o WooCommerce, o plugin não é ativado.
PHP: 8.0 ou superior.
Moeda da loja: 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, 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 o seu site: a Mollie envia webhooks para a sua loja, por isso o site precisa estar acessível pela internet. Sem webhooks, os pedidos ainda são atualizados quando o cliente volta 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_, as de produção com live_. Os métodos de pagamento em si 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 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_mollie_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Mollie > Manage, ou clique em Settings embaixo do nome do plugin na página de Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira as suas chaves de API de teste e de produção (veja Configuração). Não é preciso configurar nenhum webhook na Mollie.
6. Ative Enable/Disable. Deixe Test Mode ativado até fazer um pagamento de teste e depois desmarque.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Mollie. 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 oferece suporte à moeda da loja. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Na lista de métodos de pagamento, a Mollie aparece como precisando de configuração até que o modo atual tenha uma chave de API, e mostra Test mode enquanto o modo de teste estiver ativado.
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 o valor anterior é mantido.
Finalização de compra
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. Padrão: Mollie.
Description: a descrição do método de pagamento exibida ao cliente durante a finalização de compra. Padrão: Pay securely via Mollie.
Chaves de API
Encontre as suas chaves de API em Mollie Dashboard > Developers > API keys. Não é preciso configurar webhooks: o plugin envia a sua URL de webhook com cada pagamento. A URL aparece nesta seção e tem esta aparência: https://your-site/?wc-api=molg_mollie_webhook. Ela precisa estar acessível pela internet, senão os pedidos só são atualizados quando o cliente volta da Mollie.
Test Mode: Enable test mode usa a chave de API de teste para os novos pagamentos. Nenhum pagamento real é processado. Na página de pagamento de teste da Mollie você pode escolher o resultado (paid, failed, cancelled, expired). Os clientes veem Test mode: no real payment will be made. na finalização de compra. Pagamentos feitos no outro modo continuam usando a chave do próprio modo para consultas de status e reembolsos. Padrão: ativado.
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_).
Pedidos
Order Status After Payment: o status do pedido a ser definido após um pagamento bem-sucedido. O status é definido em uma única etapa, sem uma segunda mudança de status.
Avançado
Logging: Enable debug logging grava as chamadas de API e os webhooks em WooCommerce > Status > Logs, origem wcp_mollie_gateway. Os erros são sempre registrados. Chaves de API e dados de clientes nunca são registrados. Padrão: desativado.
Delete Data on Uninstall: Remove the plugin settings and logs when uninstalling. Quando marcado, as configurações do plugin e os seus arquivos de log são apagados ao excluir o plugin. Os IDs de pagamento da Mollie salvos nos pedidos são mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Mollie) e faz o pedido. O plugin 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 da Mollie. Lá o cliente escolhe um dos métodos de pagamento ativados na sua conta Mollie e paga.
Os webhooks da Mollie não têm assinatura, apenas o ID do pagamento. Por isso o plugin nunca confia em um webhook por si só: ele busca o pagamento na API da Mollie com a sua própria chave de API, confere se o pagamento pertence ao pedido e compara o valor pago e a moeda com o pedido. O pedido só é marcado como pago depois que a Mollie confirma dessa forma. O plugin trata estes status de pagamento da Mollie:
Quando o cliente volta, o plugin confere o último pagamento na API da Mollie da mesma forma. Um pagamento feito leva à página de pedido recebido. Se o pagamento foi cancelado, falhou, expirou ou não foi concluído, o cliente vai para a página Pay for order 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.
Quando o cliente paga de novo, o pagamento da Mollie ainda aberto, do mesmo valor, é reutilizado em vez de criar um segundo pagamento a ser feito. Se o total do pedido mudou, o pagamento antigo aberto é cancelado na Mollie quando a Mollie permitir. Se o pagamento antigo foi feito nesse meio-tempo, o pedido é marcado como pago sem um novo pagamento.
Se a Mollie não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, 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 errada) ou Mollie cannot accept a payment of this amount or currency. Please choose another payment method. O motivo técnico é adicionado às notas do pedido e ao 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).
O cliente escolhe o método da Mollie na página da Mollie, e não na sua finalização de compra. O plugin não tem assinaturas nem pagamentos recorrentes, cartões salvos ou mandatos, Mollie Components (campos de cartão no seu site), botões express de Apple Pay ou PayPal, nem Orders API, por isso a Mollie não oferece para esses pagamentos os métodos que exigem linhas de pedido (por exemplo, algumas variantes de Klarna, Billie ou in3). Pagamentos autorizados são capturados ou anulados no Mollie Dashboard, e não a partir do WooCommerce.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado para a Mollie e ainda não pagou.
Processing or Completed: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra o pagamento da Mollie, o método e o modo. O ID da transação é o ID do pagamento da Mollie (tr_...) que pagou o pedido.
On hold: uma transferência bancária aguarda o dinheiro, um pagamento autorizado aguarda a captura, ou a Mollie informou um chargeback. O status Em espera também é aplicado quando o valor ou a moeda pagos diferem do pedido, quando um pagamento de teste foi feito com a loja em modo de produção (nenhum dinheiro foi recebido), ou quando o pagamento chegou depois que o pedido foi cancelado. A nota do pedido explica o motivo. Confira o pagamento no Mollie Dashboard e depois processe o pedido ou reembolse o pagamento.
Failed: a última tentativa de pagamento falhou, expirou ou foi cancelada. Um pedido pago nunca é alterado. O cliente pode pagar de novo.
Se um segundo pagamento do mesmo pedido for feito, o pedido não muda novamente. Uma nota pede que você reembolse o pagamento duplicado no seu Mollie Dashboard.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Mollie (o botão mostra o seu Title). Reembolsos totais e parciais são suportados. O reembolso é enviado para o pagamento que de fato pagou o pedido, com a chave de API do modo em que foi feito, por isso essa chave precisa estar configurada. O botão só fica disponível para pedidos com um pagamento da Mollie feito. Se a Mollie recusar o reembolso, o WooCommerce mostra a mensagem de erro da Mollie e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID do reembolso da Mollie.
Reembolsos e chargebacks criados no Mollie Dashboard não são transformados em reembolsos do WooCommerce. Um chargeback adiciona uma nota.
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 > Mollie. 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 consultar o status de novo, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na 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 na 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. Administradores da loja conectados ainda veem 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 de Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é consultado de novo automaticamente em segundo plano.
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 loja (ou a moeda do pedido na página Pay for order) é suportada pela Mollie. A página de configurações mostra um aviso para cada um desses problemas.
O pagamento foi feito, mas o pedido continua em Pending payment: o webhook não consegue alcançar o seu site. A URL do webhook mostrada nas configurações precisa estar acessível pela internet (sem modo de manutenção, autenticação básica ou firewall bloqueando). O pedido também é atualizado quando o cliente volta para a loja depois de pagar.
Webhook answers Unknown payment.: a Mollie não reconhece o ID do pagamento com a sua chave de API de teste ou de produção, por exemplo um pagamento de outra conta Mollie.
Webhook answers Payment ID mismatch.: o pagamento, segundo os seus dados, não pertence ao pedido. O pedido não é alterado.
Webhook answers Failed to fetch payment.: a API da Mollie não pôde ser acessada. A Mollie tentará o webhook novamente mais tarde.
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 de novo do Mollie Dashboard.
O pagamento não é criado: a nota do pedido e o log mostram o código HTTP e a mensagem da Mollie. 401 significa chave de API errada; 422 aponta para um campo da requisição, por exemplo um valor ou uma moeda que a Mollie não aceita. Ative o Logging e veja em WooCommerce > Status > Logs, origem wcp_mollie_gateway.
O pedido está On hold: leia a nota do pedido. O motivo é uma divergência de valor ou moeda, um pagamento de teste em modo de produção, um pagamento após o cancelamento, uma transferência bancária, uma autorização sem captura ou um chargeback.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e a chave de API desse modo não está configurada. Insira-a e tente novamente.
Outras moedas: desenvolvedores podem alterar a lista de moedas com o filtro molg_supported_currencies.
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 na vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave para o novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
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 arquivos de log só são removidos se Delete Data on Uninstall estiver ativado. Caso contrário, ficam guardados para uma reinstalação posterior. Pedidos existentes mantêm as notas de pagamento, os IDs de pagamento da Mollie e os IDs de transação.
Mollie é uma marca registrada de seu respectivo titular. Este plugin não é afiliado à Mollie nem endossado por ela.