VibeFox Nets Nexi for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior com a extensão cURL. O módulo se recusa a instalar em versões mais antigas do PHP ou sem cURL.
Conta Nets: você precisa das chaves secretas da sua conta Nets Easy (teste e produção). Somente as chaves secretas são usadas. As chaves de checkout não são necessárias, porque os clientes pagam na página de pagamento hospedada pela Nets.
Moedas e métodos de pagamento: o módulo não restringe moedas nem países por conta própria. Use as moedas ativadas na sua conta Nets; uma moeda não suportada é informada pela Nets na criação do pagamento. Os métodos de pagamento que o cliente vê dependem do seu contrato com a Nets, do país e da moeda.
HTTPS para webhooks: a Nets só chama endereços HTTPS públicos com no máximo 256 caracteres e sem "&", então sua loja precisa de HTTPS e URLs amigáveis para receber webhooks. Sem webhooks, o pagamento ainda é confirmado quando o cliente volta à loja ou com a verificação de status na página do pedido.
Chave de licença VibeFox: comprada 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 encontre depois VibeFox Nets Nexi Gateway 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. Copie a chave secreta de teste do portal de teste da Nets Easy e cole em Test Secret Key (veja Configuração).
5. Ative Enable/Disable, mantenha Test Mode ativado, clique em Save e faça um pedido de teste. Depois insira a chave secreta de produção e desative Test Mode.
Na instalação, o módulo cria o status de pedido Nets payment on hold. O PrestaShop vincula um novo módulo de pagamento apenas aos países ativos no momento da instalação. Verifique as moedas, os países e os grupos de clientes do módulo em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Nets Nexi Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando a chave secreta do modo selecionado está ausente, por exemplo com Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set., e mostra Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged. enquanto o modo de teste estiver ativado.
Nets Nexi (países nórdicos)
O título da seção mostra TEST ou LIVE para o modo selecionado.
Enable/Disable: Enable Nets Nexi Gateway ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o título do método de pagamento exibido aos clientes durante a finalização da compra. É também o nome do método de pagamento salvo no pedido. Padrão: Nets Easy. Obrigatório: um título vazio gera o erro Enter a title for the payment method. e nada é salvo.
Description: a descrição do método de pagamento exibida aos clientes durante a finalização da compra. Padrão: Pay securely with Nets Easy.
Chaves de API
Copie as chaves secretas do portal Nets Easy em Company > Integration: o portal de teste (test.portal.dibspayment.eu) para a chave de teste e o portal de produção (portal.dibspayment.eu) para a chave de produção. As chaves de checkout não são necessárias.
Test Mode: o modo de teste usa test.api.dibspayment.eu com a chave secreta de teste; o modo de produção usa api.dibspayment.eu com a chave secreta de produção. Reembolsos e capturas de um pedido sempre usam o ambiente em que ele foi pago. Padrão: ativado. Enquanto estiver ativado, os clientes veem Test mode: no real money will be charged. abaixo do método de pagamento.
Test Secret Key: sua chave secreta de API do ambiente de teste da Nets.
Live Secret Key: sua chave secreta de API do ambiente de produção da Nets.
As chaves 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 secrets: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Pagamento
Webhooks: as notificações da Nets (webhooks) são registradas automaticamente com cada pagamento. Não há nada a configurar no portal da Nets. A seção mostra o endereço para onde são enviadas. Com URLs amigáveis, ele tem este formato: https://your-shop/module/wcp_nets_nexi_gateway/webhook, possivelmente com um código de idioma como /en/. Se o endereço não for um HTTPS público, a seção avisa que a loja não recebe webhooks; nesse caso os pagamentos são confirmados quando o cliente volta à loja ou com Nets: check payment status and capture: na página do pedido. Estes eventos são registrados:
Cada webhook precisa trazer o segredo aleatório que o módulo criou para aquele pagamento. Webhooks sem o segredo correto são rejeitados. O webhook apenas informa ao módulo qual pagamento mudou: o pagamento em si é sempre consultado na API da Nets com a chave secreta do ambiente em que foi feito. 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.
Order Status After Payment: o status do pedido depois que a Nets confirmou e cobrou o pagamento.
Avançado
Debug log: registra chamadas à API e mudanças de status de pagamento em logs/nng_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 não 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: exclui as configurações do módulo e os logs ao desinstalá-lo. Os dados de pagamento gravados nos pedidos são sempre mantidos. Padrão: desativado.
Finalização da compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Nets Easy) e confirma. O módulo cria um pagamento na Nets pelo total do carrinho na moeda do carrinho, com os produtos, o frete, a embalagem para presente e os descontos como itens do pedido, e envia o cliente à página de pagamento hospedada pela Nets. A referência do pagamento na Nets é o número do carrinho. E-mail, nome, endereço e telefone do cliente são enviados à Nets quando ela aceita o formato. O link para a página de termos e condições da sua finalização de compra aparece na página da Nets (se nenhuma estiver definida, aparece a página inicial da loja). Nesse ponto, ainda não existe nenhum pedido.
Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Nets confirma: o módulo consulta o pagamento na API da Nets, compara o valor reservado e a moeda com o carrinho, cobra a reserva e só então cria o pedido. Isso acontece no webhook ou no retorno do cliente, o que vier primeiro. Em seguida, o cliente vê a página padrão de confirmação do pedido. Se o pagamento ainda não puder ser confirmado (a Nets não respondeu, ou outra requisição estava confirmando naquele momento), uma página de Payment confirmation mostra Your Nets payment is being confirmed. Your order will be created as soon as it is confirmed — please do not pay again. com os botões Check again e Back to checkout.
Se o cliente cancelar na página da Nets, volta à finalização da compra com The Nets payment was cancelled. You can try again or choose another payment method. Se nada foi pago, a mensagem é The payment was not completed. You can try again or choose another payment method. O carrinho é mantido. Em uma nova tentativa, o módulo verifica primeiro o pagamento anterior; se ele já estiver pago, o pedido é criado em vez de um novo pagamento. Caso contrário, a sessão Nets anterior é fechada antes de iniciar uma nova.
Se a Nets não conseguir iniciar o pagamento, o cliente permanece na finalização da compra com uma mensagem curta, por exemplo Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method., This payment method is temporarily unavailable. Please choose another payment method. ou The payment service could not be reached. Please try again in a moment. Um total de carrinho igual a zero exibe The order total must be greater than zero to pay with Nets. Os detalhes são gravados no log.
O módulo usa apenas a página de pagamento hospedada. Não há checkout Nets incorporado na página, assinaturas ou pagamentos recorrentes, cartões salvos, taxas de fatura, modo somente autorização nem capturas parciais por envio.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à Nets e não pagou, ou o pagamento ainda não foi confirmado. Existe apenas o carrinho.
Payment accepted or Delivered: a Nets confirmou e cobrou o pagamento. O status segue Order Status After Payment. O pagamento é registrado com o ID de pagamento da Nets como ID de transação, e uma nota mostra o ID do pagamento, o ID da cobrança e o método de pagamento.
Nets payment on hold: o valor ou a moeda na Nets diferem do carrinho (não capturado), a captura foi recusada, ou o cliente pagou depois que o pedido havia sido cancelado (reservado, não capturado). A nota explica. Nada é capturado automaticamente. Depois de revisar o pedido, capture com Nets: check payment status and capture, ou cancele a reserva no portal da Nets.
Canceled: a reserva de um pedido em espera foi cancelada, por exemplo no portal da Nets.
Refunded: o pagamento foi reembolsado integralmente pelo módulo.
Webhooks repetidos e recarregamentos nunca cobram duas vezes nem adicionam notas duplicadas, e um pedido pago nunca é alterado novamente por eventos da Nets. Se um link de pagamento antigo for concluído para um pedido já pago, a segunda reserva é liberada automaticamente; se já tiver sido cobrada, uma nota pede que você a reembolse no portal da Nets.
Bloco de pagamento Nets Easy
A página do pedido mostra um bloco Nets Easy payment com o ID do pagamento, o ID da cobrança, o ambiente (com um selo Test environment para pagamentos de teste), o status, os valores reservados e cobrados na Nets, o total do pedido e o valor reembolsado, o histórico de reembolsos e as Nets notes do pedido. Os botões do bloco funcionam para qualquer funcionário que possa editar pedidos; não é preciso acesso às páginas de Modules.
Nets: check payment status and capture: exibido para pedidos que ainda não estão pagos. Ele consulta o pagamento na Nets e captura uma reserva que corresponde ao pedido, inclusive depois de uma captura com falha ou depois que você revisou um pedido em espera. Se nada mudar, uma nota explica o motivo, por exemplo que o cliente ainda não concluiu o pagamento.
Reembolsos
No bloco Nets Easy payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Nets. Confirme a pergunta Refund this amount through Nets? This cannot be undone. Reembolsos totais e parciais são aceitos depois que o pagamento foi cobrado; um pagamento apenas reservado pode ser cancelado no portal da Nets. O reembolso vai para a cobrança do pedido no ambiente em que foi pago. Se a Nets não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso na Nets. Um reembolso total coloca o pedido em Refunded; um reembolso parcial não altera o status.
O módulo não gera notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Nets. Reembolsos feitos no portal da Nets não são sincronizados; atualize o pedido 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 Nets Nexi Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Nets Nexi 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 deles ficam a linha Product: presta-payment-nets-nexi 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 do 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 único domínio: o domínio da loja principal, inclusive 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 Nets não é exibida aos clientes na finalização da 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 testá-lo na finalização da 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 de novo 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 Nets Nexi não aparece na finalização da compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o modo selecionado tem uma chave secreta: Test Secret Key no modo de teste, Live Secret Key no modo de produção. A página de configurações mostra um aviso quando a chave está ausente. 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 chegou à sua loja. Verifique se a loja usa HTTPS e URLs amigáveis, para que o endereço em Webhooks seja um HTTPS público sem "&", e se a chave secreta do ambiente do pagamento está definida. O pedido também é criado quando o cliente volta à loja depois de pagar.
O webhook responde Unauthorized: o webhook não trazia o segredo daquele pagamento. Webhooks só são aceitos com o segredo registrado junto com o pagamento.
O webhook responde Busy, retry later, Payment lookup failed ou Payment not reserved yet: outra requisição estava confirmando o mesmo carrinho, a API da Nets não respondeu, ou a reserva ainda não estava visível. A Nets repete o webhook automaticamente.
O webhook responde Order could not be created, retry later: o pedido não pôde ser criado, por exemplo porque o módulo está desativado. Ative Debug log para ver o motivo.
A URL do webhook mostra Method not allowed no navegador: isso é normal. O endereço aceita apenas requisições da Nets.
O cliente vê um erro ao escolher a Nets: ative Debug log e veja o campo Log na página do módulo. This payment method is temporarily unavailable. Please choose another payment method. normalmente indica uma chave secreta incorreta ou ausente. Uma moeda recusada é informada pela Nets no log.
O pedido está em Nets payment on hold após o pagamento: leia as Nets notes no bloco. Se a captura foi recusada, tente novamente com Nets: check payment status and capture ou cobre no portal da Nets. Se o valor ou a moeda não coincidirem, verifique o pagamento no portal da Nets. Se o cliente pagou depois do cancelamento, revise o pedido e capture ou cancele a reserva.
O Refund via Nets está ausente ou falha: reembolsos só são possíveis depois que o pagamento foi cobrado; o bloco então mostra um ID de cobrança. Um reembolso usa a chave secreta do ambiente em que o pedido foi pago, por isso essa chave precisa estar definida; caso contrário, o bloco informa qual chave de ambiente está faltando.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Nets Nexi 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 posterior. Os dados de pagamento da Nets dos pedidos (pagamentos, cobranças e reembolsos) e o status de pedido Nets payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Nets, Nets Easy e Nexi são marcas comerciais de seus respectivos proprietários. Este módulo não é afiliado nem endossado pela Nets ou pela Nexi.