VibeFox Nets Nexi for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

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 plugin não restringe moedas nem países. Use as moedas ativadas na sua conta Nets; uma moeda não suportada é informada pela Nets ao criar o pagamento. Quais métodos de pagamento o cliente vê depende do seu contrato com a Nets, do país e da moeda.

HTTPS para webhooks: a Nets só chama endereços HTTPS públicos de no máximo 256 caracteres e sem "&", então o seu site precisa de HTTPS e de permalinks amigáveis para receber webhooks. Em outros sites, o pagamento ainda é confirmado quando o cliente retorna à loja ou pela ação do pedido.

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_nets_nexi_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Nets Nexi (Nordics) > Manage, ou clique em Settings embaixo do nome do plugin na página 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. Copie a chave secreta de teste do portal de testes da Nets Easy e cole-a em Test Secret Key (veja Configuração).

6. Ative Enable/Disable, mantenha Test Mode ativado e faça um pedido de teste. Depois insira a chave secreta de produção e desmarque Test Mode.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Nets Nexi (Nordics). Acima dos campos, a página avisa quando a chave secreta do modo selecionado está ausente (o método de pagamento fica oculto na finalização de compra), 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 ativo. Na lista de métodos de pagamento, o Nets Nexi aparece como pendente de configuração até que o modo selecionado tenha uma chave secreta.

Geral

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 na finalização de compra. Padrão: Nets Easy.

Description: a descrição do método de pagamento exibida aos clientes na finalização de 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 testes (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: Enable 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.

Test Secret Key: a sua chave secreta de API do ambiente de teste da Nets.

Live Secret Key: a sua chave secreta de API do ambiente de produção da Nets.

Pagamento

As notificações da Nets (webhooks) são registradas automaticamente com cada pagamento. Não há nada a configurar no portal da Nets. Esta seção mostra a URL do webhook. Ela tem este formato: https://your-site/wc-api/nng_nets_nexi/. Se a URL não for um endereço HTTPS público, a seção avisa que o site não recebe webhooks; nesse caso, os pagamentos são confirmados quando o cliente retorna à loja ou pela ação do pedido Nets: check payment status and capture. Estes eventos são registrados:

Cada webhook deve trazer o segredo aleatório que o plugin criou para aquele pedido. Webhooks sem o segredo correto são rejeitados. O webhook apenas informa ao plugin qual pagamento mudou: o pagamento em si é sempre consultado na API da Nets com a sua chave secreta.

Order Status After Payment: o status do pedido quando a Nets confirma e cobra o pagamento. O status é definido de uma vez, para que o cliente receba um único e-mail.

Avançado

Debug log: Enable debug logging registra chamadas à API e mudanças de status de pagamento em WooCommerce > Status > Logs, origem wcp_nets_nexi_gateway. Erros são sempre registrados. Chaves e dados de clientes não são registrados. Padrão: desativado.

Delete Data on Uninstall: Delete the plugin settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os dados de pagamento guardados nos pedidos são sempre mantidos. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Nets Easy) e faz o pedido. O plugin cria um pagamento Nets com os itens do pedido, o frete e as taxas na moeda do pedido, e envia o cliente à página de pagamento hospedada pela Nets. O e-mail, o nome, o endereço e o telefone do cliente são transmitidos à Nets quando ela aceita o formato; a página dos seus termos e condições é linkada na página da Nets. No modo de teste, a finalização de compra mostra Test mode: no real money will be charged.

O cliente paga e volta para a página de pedido recebido da sua loja. O pedido só é marcado como pago depois que a Nets confirma: o plugin consulta o pagamento na API da Nets, compara o valor e a moeda reservados com o pedido, cobra a reserva e só então conclui o pedido. Isso acontece pelo webhook, quando o cliente retorna à página de pedido recebido, ou pela ação do pedido Nets: check payment status and capture.

Se o cliente cancelar na página da Nets, ele volta à finalização de compra ou à página Pay for order com a mensagem The Nets payment was cancelled. You can try again or choose another payment method. Um cliente pode pagar novamente um pedido não pago. O plugin verifica primeiro o pagamento anterior; se ele já estiver pago, o pedido é confirmado. Caso contrário, a sessão Nets anterior é encerrada antes de começar uma nova. Se um pagamento do pedido estiver retido para a sua análise, o cliente vê A payment for this order is already being reviewed by the shop. Please contact us instead of paying again.

Se a Nets não conseguir iniciar o pagamento, o cliente vê 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. ou The payment service could not be reached. Please try again in a moment. Os detalhes são gravados no 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 plugin usa somente 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

Pending payment: o cliente foi enviado à Nets e ainda não pagou. A nota do pedido mostra o ID do pagamento Nets, o valor e o ambiente.

Processing or Completed: a Nets confirmou e cobrou o pagamento. O status segue Order Status After Payment. A nota do pedido mostra o ID do pagamento, o ID da cobrança e o método de pagamento. O ID da transação é o ID do pagamento Nets.

On hold: o valor ou a moeda na Nets diferem do pedido (não capturado), a captura foi recusada, ou o cliente pagou depois que o pedido já havia sido cancelado (reservado, não capturado). A nota do pedido explica isso. Depois de revisar o pedido, capture com a ação Nets: check payment status and capture, ou cancele a reserva no portal da Nets.

Cancelled: a reserva do último pagamento do pedido foi cancelada, por exemplo no portal da Nets.

Webhooks repetidos e recarregamentos nunca cobram duas vezes nem acrescentam notas, baixas de estoque ou e-mails duplicados, e um pedido que foi pago, reembolsado ou cancelado após o pagamento nunca é reaberto. Se um link de pagamento antigo for concluído para um pedido que já está pago, a segunda reserva é liberada automaticamente; se ela já tiver sido cobrada, uma nota pede que você a reembolse no portal da Nets.

Ação do pedido

Para pedidos não pagos com um pagamento Nets, a lista de ações do pedido inclui Nets: check payment status and capture. Ela consulta o pagamento na Nets e captura uma reserva correspondente. Se nada mudar, uma nota explica o motivo, por exemplo que o cliente ainda não concluiu o pagamento.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Nets Easy (o botão usa o título do método de pagamento). 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 é feito sobre a cobrança do pedido no ambiente em que ele foi pago. Se a Nets não aceitar o reembolso, o WooCommerce exibe o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID do reembolso Nets.

Reembolsos feitos diretamente no portal da Nets não se tornam reembolsos do WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem usar Refund via Nets Easy.

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 > Nets Nexi (Nordics). 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 verificar o status novamente, 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 na sua conta vibefox.net.

Sem uma chave ativa, o Nets Nexi não é mostrado 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. Gerentes 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 Plugins e nas páginas do WooCommerce. Os 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 é verificado novamente de forma automática em segundo plano.

Solução de problemas

O Nets Nexi não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado 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á faltando.

O pagamento foi feito, mas o pedido continua em Pending payment: o webhook não chegou à sua loja. Verifique se o site usa HTTPS e permalinks amigáveis, de modo que a URL do webhook na seção Payment seja um endereço HTTPS público sem "&", e se a chave secreta do ambiente do pagamento está definida. Depois use a ação do pedido Nets: check payment status and capture. O pedido também é confirmado quando o cliente retorna à página de pedido recebido.

Webhook answers Unauthorized: o webhook não trouxe o segredo daquele pedido. Os webhooks só são aceitos com o segredo registrado no pagamento.

Webhook answers Busy, retry later, Payment lookup failed ou Payment not reserved yet: outra solicitação estava atualizando o pedido, a API da Nets não pôde ser acessada, ou a reserva ainda não estava visível. A Nets tenta o webhook novamente automaticamente.

O cliente vê um erro ao fazer o pedido: ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_nets_nexi_gateway. This payment method is temporarily unavailable. Please choose another payment method. geralmente indica uma chave secreta errada ou ausente. Uma moeda recusada é informada pela Nets no log.

Order is On hold after payment: leia a nota do pedido. Se a captura foi recusada, tente novamente com a ação do pedido Nets: check payment status and capture ou cobre no portal da Nets. Se o valor ou a moeda diferirem, verifique o pagamento no portal da Nets. Se o cliente pagou após o cancelamento, revise o pedido e capture ou cancele a reserva.

Refund via Nets Easy está ausente ou falha: reembolsos só são possíveis depois que o pagamento foi cobrado. Verifique na nota do pedido se a cobrança existe. Um reembolso usa a chave secreta do ambiente em que o pedido foi pago, então essa chave precisa estar definida.

The license block shows an error: 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 vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no 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 logs só são removidos se Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Nets, Nets Easy e Nexi são marcas registradas de seus respectivos proprietários. Este plugin não é afiliado nem endossado pela Nets ou pela Nexi.