VibeFox MakeCommerce 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 mais antigas do PHP.
Acesso à internet para a sua loja: a MakeCommerce envia notificações de pagamento para a sua loja, por isso o site deve estar acessível pela internet. Um firewall ou a autenticação básica podem bloqueá-las. O modo de manutenção e a restrição de países da sua loja não as bloqueiam.
Conta MakeCommerce: você precisa do Shop ID e da Secret key, disponíveis no Merchant Portal da MakeCommerce (Settings > API). Os ambientes de teste e de produção têm contas e chaves separadas. Quais métodos de pagamento e moedas estão disponíveis é definido pelo seu contrato com a MakeCommerce. Moedas com três casas decimais, como KWD ou BHD, não são oferecidas.
Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um único 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, mais tarde, localize VibeFox MakeCommerce Payment na lista de módulos e clique em Configure.
3. Insira sua chave de licença VibeFox em License key no bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Insira o Shop ID e a Secret key do ambiente de teste e, para pagamentos reais, as chaves de produção (veja Configuração). Não é preciso configurar nada no Merchant Portal.
5. Ative Enable/Disable e clique em Save. Teste um pagamento com Test mode ativado e, em seguida, desative-o para aceitar pagamentos reais.
Ao ser instalado, o módulo cria o status de pedido MakeCommerce payment on hold. O PrestaShop oferece o 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 MakeCommerce 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 mostra Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged. enquanto o modo de teste estiver ativado. Ela avisa quando o método está habilitado, mas o Shop ID ou a Secret key do ambiente atual estão vazios, e quando a moeda padrão da loja não pode ser cobrada pela MakeCommerce. Nos dois casos, o método fica oculto na finalização de compra. Ao salvar, os espaços são removidos das chaves.
MakeCommerce
Enable/Disable: Enable MakeCommerce payments liga ou desliga o método de pagamento. Padrão: desligado.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Bank link or card (MakeCommerce). Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page.
Conta MakeCommerce
O Shop ID e a Secret key estão no Merchant Portal da MakeCommerce, em Settings > API. O portal de teste e o portal de produção têm contas e chaves separadas. A seção tem links para os dois portais e para a página de cadastro da MakeCommerce.
Test mode: usa o ambiente de teste da MakeCommerce (nenhum dinheiro real é cobrado). Novos pagamentos são criados no ambiente selecionado, com as suas chaves. Cada pedido guarda o ambiente em que foi pago: as verificações de status e os reembolsos sempre vão para lá. Enquanto estiver ativado, os clientes veem TEST MODE — MakeCommerce test environment, no real money is charged. abaixo do método de pagamento. Padrão: ligado.
Test Shop ID: o Shop ID da sua conta de teste, no formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
Test Secret key: a Secret key da sua conta de teste.
Live Shop ID: o Shop ID da sua conta de produção.
Live Secret key: a Secret key da sua conta de produção.
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 se quiser alterá-lo.
Clear saved secret keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Notificações de pagamento
Não é preciso configurar nada no Merchant Portal. Callback URLs mostra, apenas como referência, o endereço de retorno ou cancelamento do cliente e o endereço das notificações de pagamento. Cada transação carrega suas próprias URLs de retorno, cancelamento e notificação, formadas a partir desses endereços com o número do carrinho e uma chave adicionada. A MakeCommerce envia uma mensagem assinada para a URL de notificação (de servidor para servidor) e, pelo navegador do cliente, para a URL de retorno ou cancelamento. A assinatura é verificada com a Secret key do ambiente em que a transação foi criada. Mensagens sem assinatura válida são rejeitadas.
O módulo trata estes status de transação da MakeCommerce:
O pagamento também é confirmado quando o cliente retorna à loja. Se o cliente voltar sem uma mensagem assinada, o módulo consulta o status na API da MakeCommerce.
Avançado
Debug log: registra as chamadas à API e as notificações de pagamento em logs/wc_mkc_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros são sempre registrados. Chaves e dados de clientes nunca são registrados. Padrão: desligado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete data: quando ligado, desinstalar o módulo remove as configurações do módulo e o log. Pedidos e seus dados de pagamento da MakeCommerce são sempre mantidos. Padrão: desligado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Bank link or card (MakeCommerce)) e confirma. O módulo cria uma transação na MakeCommerce pelo total do carrinho, na moeda do carrinho, e envia o cliente à página de pagamento da MakeCommerce. Lá, o cliente escolhe um link bancário ou um cartão. O e-mail e o país do cliente são repassados à MakeCommerce, e a página abre no idioma da loja quando a MakeCommerce oferece suporte a ele (estoniano, inglês, letão, lituano, finlandês, russo, alemão, polonês); caso contrário, em inglês. Neste ponto, ainda não existe pedido.
Depois de pagar, o cliente retorna à sua loja. O pedido só é marcado como pago depois que a MakeCommerce confirma: pela notificação assinada ou pelo retorno assinado do cliente, com uma verificação da transação pela API da MakeCommerce. Em seguida, o pedido é criado e o cliente vê a página padrão de confirmação do pedido, com Your MakeCommerce payment has been received. Se o pedido foi colocado em espera para análise, a página mostra Your MakeCommerce payment was received and is being reviewed by the shop.
Se o pagamento foi aprovado, mas ainda não concluído, ou se a MakeCommerce não puder ser acessada, uma página Payment confirmation mostra We could not confirm your payment yet. If you completed it, your order will be updated automatically — please do not pay again. com os botões Check again e Back to checkout. A notificação cria o pedido assim que o pagamento for concluído.
Se o cliente cancelar na página da MakeCommerce, ou se o pagamento expirar ou falhar, ele volta à finalização de compra com uma mensagem, por exemplo The payment was cancelled. You can try again or choose another payment method., The payment session expired. Please try again. ou The payment was not completed. Please try again or choose another payment method. O carrinho é mantido, e o cliente pode pagar novamente. Cada tentativa é uma nova transação na MakeCommerce. Um link de pagamento anterior do mesmo carrinho continua funcionando, e o carrinho não pode ser pago duas vezes em dois pedidos.
Se a MakeCommerce não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com MakeCommerce is temporarily unavailable. Please try again in a moment or choose another payment method. ou MakeCommerce could not start the payment for this order. Please choose another payment method or contact us. O motivo técnico é gravado no log.
O banco ou o cartão é escolhido na página da MakeCommerce, não na sua finalização de compra. O módulo não possui cartões salvos, pagamentos recorrentes ou assinaturas, nem envio pela MakeCommerce (armários de encomendas, etiquetas).
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à MakeCommerce e ainda não pagou, ou a MakeCommerce ainda não confirmou o pagamento. Existe apenas o carrinho.
Payment accepted: o pagamento foi confirmado. Ele é registrado com o ID da transação da MakeCommerce, e uma nota mostra o valor, a transação, o ambiente e como foi verificado (API da MakeCommerce ou notificação assinada).
MakeCommerce payment on hold: o valor ou a moeda pagos eram diferentes do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou), o valor estava ausente, a transação na MakeCommerce ainda não era definitiva, embora informada como concluída, ou o pagamento chegou depois que o pedido havia sido cancelado. A nota explica o motivo. Se a moeda paga for a moeda do pedido, o valor efetivamente pago é registrado no pedido. Uma transação com divergência nunca paga o pedido depois; uma transação que ainda não era definitiva conclui o pedido quando a MakeCommerce informa que ela foi concluída. Verifique a transação no Merchant Portal e, em seguida, atenda o pedido ou reembolse o pagamento.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse o duplicado no Merchant Portal da MakeCommerce.
Bloco de pagamento MakeCommerce
A página do pedido mostra um bloco MakeCommerce payment com todas as transações da MakeCommerce do carrinho (data, ID da transação, um selo Test para pagamentos de teste, valor, status e resultado da MakeCommerce), os valores pagos e reembolsados, o histórico de reembolsos e as MakeCommerce notes do pedido. Os botões do bloco exigem apenas a permissão para editar pedidos, não acesso aos módulos.
Check MakeCommerce payment status: consulta na API da MakeCommerce o status das transações do carrinho (as mais recentes primeiro), aplica o status e adiciona uma nota com o resultado. Use-o quando um cliente disser que pagou, mas o pedido não foi concluído.
Reembolsos
No bloco MakeCommerce payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via MakeCommerce. Confirme a pergunta Refund this amount via MakeCommerce? Reembolsos totais e parciais são suportados. Os reembolsos ficam limitados ao valor e à moeda da transação na MakeCommerce; assim, 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 ao ambiente em que o pagamento foi feito (teste ou produção), por isso as chaves desse ambiente precisam estar configuradas. O motivo é enviado à MakeCommerce como comentário do reembolso; sem motivo, o comentário é Refund for order e a referência do pedido. Se a MakeCommerce não aceitar o reembolso, o bloco mostra o erro, uma nota é adicionada e nenhum reembolso é registrado. Se a MakeCommerce ainda estiver processando o pagamento, a mensagem é MakeCommerce is still processing this payment — try the refund again later. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso na MakeCommerce. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis depois que a MakeCommerce confirma o pagamento.
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 MakeCommerce.
Reembolsos feitos no Merchant Portal chegam com o status da transação e são adicionados às notas. O status do pedido e as notas de crédito não são alterados automaticamente.
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 MakeCommerce Payment é o primeiro bloco de Modules > Module Manager > VibeFox MakeCommerce Payment > Configure, 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 estão a linha Product: presta-payment-makecommerce e o link Manage licenses and domains in your account, que abre a sua conta na 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 (inclui inglês e russo).
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 único 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 MakeCommerce 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. 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ê: você pode configurar o módulo antes de comprar uma chave, mas não pode 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: os 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 precisam de 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 chave ser informada, 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 MakeCommerce não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o ambiente atual tem suas chaves: Test Shop ID e Test Secret key no modo de teste, Live Shop ID e Live Secret key no modo de produção. Verifique se a moeda do carrinho tem no máximo duas casas decimais. 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 concluído, mas nenhum pedido foi criado: as notificações não conseguiram chegar à loja, por exemplo por causa de um firewall ou da autenticação básica. O pedido também é criado quando o cliente retorna à loja ou clica em Check again. Verifique se as chaves do ambiente em que o pagamento foi feito estão configuradas: a notificação é verificada com a Secret key desse ambiente e, sem ela, a MakeCommerce recebe um erro e tenta de novo. Ative o Debug log para ver as notificações.
O pedido está em MakeCommerce payment on hold: leia as MakeCommerce notes no bloco da página do pedido (veja Status do pedido), verifique a transação no Merchant Portal e, em seguida, atenda o pedido ou reembolse o pagamento.
As notificações são rejeitadas: uma mensagem com assinatura incorreta, para outro carrinho, outra loja ou uma transação não criada para o carrinho é rejeitada, e nada é alterado. Verifique se o Shop ID e a Secret key pertencem à mesma conta e ao mesmo ambiente da MakeCommerce.
O cliente vê um erro ao escolher a MakeCommerce: ative o Debug log e consulte o campo Log na página do módulo. Uma moeda que a MakeCommerce não consegue cobrar gera MakeCommerce cannot process payments in e o código da moeda.
O reembolso falha com uma mensagem sobre o ambiente: o pedido foi pago no ambiente de teste ou de produção, e as chaves desse ambiente não estão configuradas. Insira-as e tente novamente.
O reembolso falha com No MakeCommerce transaction ID found for this order: o pedido não tem um pagamento confirmado na MakeCommerce. Reembolse-o no Merchant Portal.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox MakeCommerce 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 ligado, as configurações do módulo e o log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação posterior. As transações e os reembolsos da MakeCommerce e o status de pedido MakeCommerce 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 suas notas de pagamento e IDs de transação.
MakeCommerce é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela MakeCommerce.