VibeFox Montonio for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.

Moeda: a moeda do carrinho deve ser EUR ou PLN. Para qualquer outra moeda, a forma de pagamento fica oculta na finalização de compra.

Conta Montonio: você precisa da chave de acesso e da chave secreta da sua loja no Montonio Partner System. As chaves de sandbox e de produção são diferentes, então você precisa de um par para cada ambiente que usar. Não há mais nada a configurar na Montonio: o endereço de notificação é enviado com cada pagamento.

Site público: a sua loja precisa estar acessível pela internet para receber as notificações da Montonio. Caso contrário, os pedidos continuam sendo criados quando o cliente volta para a loja.

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 VibeFox Montonio Payment na lista de módulos e clique em Configure.

3. Insira 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. No Montonio Partner System, abra Stores > your store > API keys e copie a chave de acesso e a chave secreta de sandbox. Cole-as nas configurações e mantenha Sandbox mode ativado.

5. Ative Enable/Disable, clique em Save e teste um pagamento no sandbox. Depois, insira as chaves de produção e desative Sandbox mode.

Ao ser instalado, o módulo cria o status de pedido Montonio 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 estão na página do módulo: Modules > Module Manager > VibeFox Montonio Payment > 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 as chaves do ambiente atual estão faltando (a forma de pagamento fica então oculta na finalização de compra), quando a moeda da loja não é EUR ou PLN, e mostra Sandbox mode is on: payments are simulated and no real money is charged. enquanto o sandbox estiver ativo. Title não pode ficar vazio.

Montonio

Enable/Disable: Enable Montonio bank payments ativa ou desativa a forma de pagamento. Padrão: desativado.

Title: o nome da forma de pagamento que os clientes veem na finalização de compra. Também é o nome da forma de pagamento salvo no pedido. Padrão: Bank payment (Montonio). Obrigatório.

Description: o texto exibido abaixo da forma de pagamento na finalização de compra. Padrão: Pay directly from your bank account. You will be redirected to Montonio to choose your bank.

Chaves de API

Obtenha as chaves no Montonio Partner System, em Stores > your store > API keys. As chaves de sandbox e de produção são diferentes. O sandbox usa somente as chaves de sandbox, e o modo de produção usa somente as chaves de produção.

Sandbox mode: usa o sandbox da Montonio (pagamentos de teste, sem dinheiro real). Ele troca tanto o endereço da API da Montonio quanto o par de chaves. Padrão: ativado. Desative-o somente depois de inserir as chaves de produção. Pagamentos feitos no outro ambiente continuam usando as chaves do próprio ambiente para confirmações e reembolsos.

Sandbox access key: a chave de acesso (UUID) da sua loja no sandbox da Montonio.

Sandbox secret key: a chave secreta da sua loja no sandbox da Montonio.

Live access key: a chave de acesso (UUID) da sua loja no ambiente de produção da Montonio.

Live secret key: a chave secreta da sua loja no ambiente de produção da Montonio.

As chaves secretas 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.

Clear saved secret keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Notification URL: o endereço para o qual a Montonio envia as notificações de pagamento. Com URLs amigáveis, ele tem esta aparência: https://your-shop/module/wcp_montonio_payment/webhook. Você não precisa digitá-lo em lugar nenhum: o módulo o envia à Montonio com cada pagamento.

Avançado

Debug log: grava os eventos de pagamento em logs/wc_mnt_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 quando esta opção está desativada. Chaves, tokens e dados do cliente nunca são registrados. Padrão: desativado.

Log: mostra o tamanho e as entradas mais recentes do registro. Clique em Clear log para esvaziá-lo.

Delete data: quando ativado, desinstalar o módulo remove as configurações do módulo e o seu registro. Desativar o módulo nunca apaga nada. Os dados dos pedidos (UUIDs da Montonio, notas) são sempre mantidos. Padrão: desativado.

Notificações de pagamento

A Montonio informa a sua loja sobre cada pagamento com um token assinado. O token chega de duas formas: por uma notificação servidor a servidor para a URL de notificação e com o cliente quando ele volta para a loja. Os dois são verificados: a assinatura com a chave secreta do ambiente em que o pagamento foi criado, o prazo de validade, a sua chave de acesso e se o pagamento foi criado pela sua loja para aquele carrinho. Um token assinado com a chave do outro ambiente é recusado. Cada status é aplicado apenas uma vez, então notificações repetidas não adicionam notas, e-mails nem alterações de estoque. A URL de notificação funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.

Finalização de compra

Na etapa de pagamento, o cliente escolhe a forma de pagamento (por padrão, Bank payment (Montonio)) e confirma. O módulo cria um pagamento Montonio pelo total do carrinho na moeda do carrinho e envia o cliente para a página de pagamento da Montonio. Lá, o cliente escolhe um banco e paga. Os bancos do país de cobrança do cliente aparecem primeiro (para carrinhos em PLN, a Polônia). O pagamento aparece como Order e o número do carrinho. A página da Montonio abre no idioma da loja quando ele é alemão, inglês, estoniano, finlandês, lituano, letão, polonês ou russo; caso contrário, abre em inglês. No modo sandbox, a finalização de compra mostra SANDBOX MODE — test payment, no real money is charged. abaixo da descrição. Neste ponto, ainda não existe pedido.

O pedido só é marcado como pago depois que a Montonio o confirma: pela notificação ou com o retorno do cliente. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your Montonio bank payment has been received. Se o banco ainda não tiver confirmado o pagamento, ou se o pedido estiver em espera, a página mostra We are confirming your payment with Montonio. The order will be updated automatically — please do not pay again. Se o banco recusar depois um pagamento autorizado, a página mostra Your Montonio payment was not completed. Please contact us about this order.

Se a Montonio informar que o pagamento ainda está pendente quando o cliente voltar, uma página Payment confirmation mostra o mesmo texto e um botão Check again. O botão pede à Montonio o status atual do pagamento. A notificação cria o pedido assim que chega.

Se o pagamento tiver sido cancelado ou recusado, o cliente volta à finalização de compra com uma destas mensagens: The payment was cancelled or rejected by the bank. You can try again or choose another payment method., The payment was not completed. You can try again or choose another payment method. ou Montonio could not complete the payment. Please try again or choose another payment method. O carrinho é mantido. Antes de criar um novo pagamento, o módulo consulta a Montonio sobre o anterior. Se ele já estiver pago, o pedido é criado e nenhum segundo pagamento é feito.

Se a Montonio não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Montonio is temporarily unavailable. Please try again in a few minutes or choose another payment method. O motivo técnico é gravado no registro.

O módulo aceita apenas pagamentos bancários (iniciação de pagamento). Não há pagamentos com cartão, BLIK, Apple Pay ou Google Pay, Pay Later ou financiamento, envio pela Montonio, assinaturas, formas de pagamento salvas nem seleção de banco no seu próprio site.

Pedidos e reembolsos

Status do pedido

No order yet: o cliente foi enviado à Montonio e não pagou, ou a Montonio informa o pagamento como pendente. Existe apenas o carrinho.

Payment accepted: a Montonio confirmou o pagamento (PAID) com o valor e a moeda exatos do carrinho. O pagamento é registrado com o UUID do pedido na Montonio como ID da transação, e uma nota mostra o banco, o UUID, o valor e o ambiente.

Montonio payment on hold: o banco ainda não confirmou o pagamento (AUTHORIZED); o pedido passa para Payment accepted quando a Montonio informa PAID. Um pedido também fica em espera quando a Montonio informou um valor ou uma moeda diferentes do total do carrinho, quando um pagamento de sandbox chega enquanto a loja está no modo de produção (nenhum pagamento é registrado, porque nenhum dinheiro foi recebido), ou quando o pagamento chega depois de o pedido ter sido cancelado. A nota explica o motivo. Verifique o pagamento no Montonio Partner System e processe o pedido ou reembolse o pagamento.

Payment error: o banco recusou um pagamento autorizado, ou o cliente não o concluiu. Somente o último pagamento do carrinho pode alterar o pedido.

Refunded: o pagamento foi totalmente reembolsado pelo módulo.

Pedidos pagos, cancelados ou reembolsados nunca são reabertos por notificações posteriores. Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse o segundo pagamento no Montonio Partner System.

Bloco Montonio payment

A página do pedido mostra um bloco Montonio payment com o UUID do pedido na Montonio, o ambiente (com um selo Sandbox para pagamentos de teste), o banco, o status do pagamento, o valor pago e reembolsado, o histórico de reembolsos e as Montonio notes do pedido.

Reembolsos

No bloco Montonio payment, digite o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo (ele é guardado somente na nota do pedido), e clique em Refund via Montonio. Confirme a pergunta Refund this amount through Montonio? This cannot be undone. São suportados reembolsos totais e parciais. Você precisa do direito de editar pedidos; o acesso às páginas de Módulos não é necessário. Os reembolsos são limitados ao valor cobrado pela Montonio; assim, 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 ao ambiente em que o pagamento foi feito (sandbox ou produção), por isso as chaves desse ambiente precisam estar configuradas. Se a Montonio não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso enviado é adicionado ao histórico de reembolsos e às notas, com o seu status e o ID do reembolso na Montonio. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis quando a Montonio informa que o pagamento foi pago.

A Montonio confirma ou recusa cada reembolso depois, por uma notificação. Uma confirmação é adicionada às notas. Se a Montonio recusar o reembolso, a nota diz que o dinheiro não foi devolvido ao cliente; verifique no Montonio Partner System e corrija o reembolso no PrestaShop.

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 Montonio. Os reembolsos feitos no Montonio Partner System são adicionados às notas quando a Montonio os informa. O status do pedido e as notas de crédito não são alterados automaticamente. Atualize-os manualmente, se necessário.

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 Montonio Payment é o primeiro bloco da página Modules > Module Manager > VibeFox Montonio Payment > 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 deles ficam a linha Product: presta-payment-montonio 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 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, 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 vaga na sua conta vibefox.net.

Sem uma chave ativa, a Montonio não é exibida para os 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 a forma de pagamento também fica oculta para você: é possível 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 automaticamente enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida, 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 Montonio não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se as duas chaves do ambiente atual estão preenchidas (Sandbox access key e Sandbox secret key no modo sandbox, Live access key e Live secret key no modo de produção) e se a moeda do carrinho é EUR ou PLN. A página de configurações mostra um aviso quando faltam chaves ou quando a 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: a notificação não chegou à sua loja. Verifique se a loja está acessível pela internet e se as chaves nas configurações pertencem ao ambiente do pagamento. O pedido também é criado quando o cliente volta para a loja depois de pagar, quando o cliente clica em Check again e quando o cliente tenta pagar o mesmo carrinho de novo.

A notificação responde Invalid token: a assinatura, o prazo de validade ou a chave de acesso do token não conferiram. Verifique se a chave de acesso e a chave secreta foram copiadas corretamente e pertencem ao ambiente certo, e se o relógio do servidor está correto. Um token assinado com a chave do outro ambiente também é recusado.

A notificação responde Payment does not belong to this order: o pagamento não foi criado por esta loja para este carrinho. Isso acontece quando duas lojas usam a mesma conta Montonio e os mesmos números de carrinho.

A notificação responde Gateway not configured: nenhuma chave da Montonio está definida, ou faltam as chaves do ambiente do pagamento. Insira as chaves; a Montonio repete a notificação.

A notificação responde Temporarily unavailable: o carrinho estava sendo confirmado por outra requisição naquele mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Montonio repete a notificação. Consulte o campo Log para ver o motivo.

O cliente vê um erro ao escolher a Montonio: consulte o campo Log na página do módulo. This payment method is temporarily unavailable. Please choose another payment method. normalmente indica chaves erradas ou ausentes. Montonio could not start the payment. Please check your order details or choose another payment method. significa que a Montonio recusou os dados do pagamento; o registro traz o motivo.

O pedido fica em Montonio payment on hold depois do pagamento: leia as notas no bloco Montonio payment (veja Status do pedido) e depois processe o pedido ou reembolse o pagamento.

Pagamentos em sandbox não confirmam um pedido de produção: um pagamento em sandbox nunca conclui um pedido enquanto a loja está no modo de produção; o pedido fica em espera. Mude o Sandbox mode para o ambiente desejado e use as chaves desse ambiente.

O reembolso falha com uma mensagem sobre o ambiente: o pagamento foi feito no ambiente sandbox ou de produção, e as chaves desse ambiente não estão definidas. Insira-as e tente novamente.

Para desenvolvedores, o módulo oferece os hooks actionWcpMontonioSupportedCurrencies, actionWcpMontonioOrderData e actionWcpMontonioLocale para alterar as moedas suportadas, os dados do pagamento e o idioma da página da Montonio.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Montonio Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data estiver ativado, as configurações do módulo e o registro são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de pagamentos e reembolsos da Montonio e o status de pedido Montonio payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Montonio é uma marca registrada do respectivo titular. Este módulo não é afiliado nem endossado pela Montonio.