VibeFox Nexi XPay for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo.
PHP: 8.0 ou superior.
Moeda: a moeda da loja ou do pedido precisa ser EUR. Para outras moedas, o método de pagamento fica oculto na finalização de compra.
Conta Nexi XPay: você precisa de uma conta de comerciante Nexi XPay (integração por redirecionamento "Pagamento Semplice") com o alias (ID do terminal) e a chave MAC do seu terminal. As credenciais de teste e as de produção são separadas: as de teste vêm da área de teste do Nexi XPay ou do portal de desenvolvedores (developer.nexi.it), e as de produção, do seu back office do Nexi XPay depois que a conta de comerciante for ativada. Não é preciso configurar nada no back office do Nexi: o endereço de notificação é enviado com cada pagamento.
Site público: a URL de notificação precisa estar acessível pela internet, sem modo de manutenção, autenticação básica ou regra de firewall bloqueando o Nexi. Caso contrário, o pagamento ainda é confirmado pelo retorno assinado do cliente.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_nexi_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Nexi XPay > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Mantenha Test Mode ativado e insira o alias e a chave MAC de teste (veja Configuração).
6. Ative Enable/Disable e faça um pedido de teste. Quando tudo estiver funcionando, insira o alias e a chave MAC de produção e desmarque Test Mode.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Nexi XPay. Acima dos campos, a página mostra O modo de teste está ativo: os pagamentos vão para o ambiente de teste do Nexi XPay e nenhum dinheiro real é cobrado. enquanto o modo de teste estiver ativo, e avisa quando o gateway está habilitado, mas o alias ou a chave MAC do modo atual estão vazios, ou quando a moeda da loja não é EUR. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Espaços e quebras de linha em volta das chaves coladas são removidos ao salvar.
Geral
Enable/Disable: Enable Nexi XPay Gateway ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o título do método de pagamento exibido ao cliente na finalização de compra. Padrão: Credit Card (Nexi). No modo de teste, a finalização de compra acrescenta (TEST MODE) ao título.
Description: a descrição do método de pagamento exibida ao cliente na finalização de compra. Padrão: Pay securely with your credit card via Nexi XPay.
Ambiente de teste
Os pagamentos de teste vão para int-ecommerce.nexi.it e nunca cobram cartões reais. Obtenha o alias e a chave MAC de teste na área de teste do Nexi XPay ou no portal de desenvolvedores (developer.nexi.it).
Test Mode: Enable test mode usa o ambiente de teste do Nexi XPay e as credenciais de teste. Desmarque para receber pagamentos reais com as credenciais de produção. Padrão: ativado.
Test Alias: o alias (ID do terminal) do seu terminal de teste do Nexi XPay.
Test MAC Key: a chave de cálculo MAC do seu terminal de teste do Nexi XPay.
Ambiente de produção
O alias e a chave MAC de produção são exibidos no seu back office do Nexi XPay (ecommerce.nexi.it) depois que a sua conta de comerciante for ativada.
Live Alias: o alias (ID do terminal) do seu terminal de produção do Nexi XPay.
Live MAC Key: a chave de cálculo MAC do seu terminal de produção do Nexi XPay.
Pagamento
A URL de notificação é enviada ao Nexi com cada pagamento, então nada precisa ser configurado no back office. A seção mostra a URL; ela tem a forma https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}, com o ID do pedido no final. O Nexi envia o resultado do pagamento para essa URL de servidor a servidor e também o transmite com o retorno do cliente. Os dois são assinados da mesma forma e verificados com a chave MAC do ambiente em que o pagamento foi feito, com o alias desse ambiente e com o código de transação emitido para aquele pedido. Resultados que falham na verificação são rejeitados e não alteram nada.
Capture: quando o dinheiro é cobrado.
Order Status After Payment: o status do pedido após um pagamento bem-sucedido. O status é definido de uma vez, com uma única mudança de status e um único e-mail.
Avançado
Debug Log: Enable logging registra os eventos de pagamento em WooCommerce > Status > Logs, origem wcp_nexi_gateway. Chaves MAC, dados de cartão e endereços de e-mail não são registrados. Erros e avisos, por exemplo uma verificação MAC com falha, são sempre registrados, mesmo com a opção desativada. Padrão: desativado.
Delete Data on Uninstall: Remove all plugin settings and logs when uninstalled. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Credit Card (Nexi)) e faz o pedido. A página seguinte mostra Redirecionando para o Nexi XPay para o pagamento... e envia o cliente automaticamente para a página do Nexi XPay, com um botão Pay Now como alternativa. O pagamento é enviado em EUR com um novo código de transação, o e-mail do cliente e a descrição Order, o número do pedido e o nome do seu site. A página do Nexi abre no idioma da loja se for italiano, inglês, espanhol, francês, alemão, japonês, chinês, árabe, russo ou português; caso contrário, em inglês.
O cliente paga e volta para a página de pedido recebido da sua loja. O pedido só é marcado como pago depois de um resultado verificado do Nexi com o valor e a moeda exatos do pedido: seja pela notificação de servidor a servidor, seja pelo retorno assinado do cliente, o que chegar primeiro.
Se o pagamento for recusado ou o cliente cancelar na página do Nexi, ele volta para a finalização de compra (ou para a página Pay for order, se o carrinho estiver vazio) e vê uma destas mensagens: O pagamento não foi concluído. Tente novamente ou escolha outro método de pagamento., O pagamento foi cancelado. Tente novamente. ou Não foi possível confirmar o pagamento. Se o seu cartão foi cobrado, entre em contato conosco antes de pagar novamente. Cancelar na página do Nexi deixa o pedido inalterado, então o cliente pode pagar de novo.
Se o plugin não estiver configurado para o modo atual, o cliente vê Este método de pagamento não está disponível no momento. Escolha outro método de pagamento.
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 recebe pagamentos somente na página do Nexi XPay. Não há reembolsos pelo WooCommerce, nem cartões salvos ou OneClick, nem assinaturas ou pagamentos recorrentes, nem Pay-By-Link, nem campos incorporados do XPay Build e nem métodos de pagamento selecionados no WooCommerce: a página do Nexi mostra os métodos ativados no seu terminal.
Pedidos e reembolsos
Status do pedido
Aguardando pagamento: o cliente foi enviado ao Nexi e ainda não pagou, ou cancelou na página do Nexi.
Em processamento, Concluído ou Em espera: o Nexi confirmou o pagamento. O status segue Order Status After Payment. A nota do pedido mostra o código de autorização, o código de transação, a bandeira do cartão e a mensagem do Nexi. O ID da transação é o código de transação do Nexi.
Em espera (autorizado): a captura adiada está selecionada e o pagamento está apenas autorizado. Capture-o com a ação de pedido Capture Nexi XPay payment.
Em espera (pendente): o Nexi informou que o pagamento aguarda confirmação. O pedido será atualizado com o resultado final.
Em espera após o pagamento: o valor ou a moeda recebidos do Nexi não correspondiam ao pedido (o pedido não é marcado como pago), ou chegou um pagamento bem-sucedido para um pedido que já tinha sido cancelado. A nota do pedido explica. Verifique o pagamento no back office do Nexi XPay e processe ou reembolse o pedido.
Falhou: a última tentativa de pagamento foi recusada, cancelada ou terminou com erro. O cliente pode pagar novamente.
Um pedido pago nunca é rebaixado por uma falha posterior. Se chegar outro pagamento bem-sucedido para um pedido já pago, uma nota pede que você o reembolse no back office do Nexi XPay caso seja uma duplicata.
Captura adiada
Para um pedido autorizado em espera, abra o pedido, escolha Capture Nexi XPay payment nas ações do pedido e clique na seta. O plugin captura o valor autorizado no ambiente do pagamento e marca o pedido como pago com o status definido em Order Status After Payment. Se a captura falhar, o erro aparece na tela do pedido e é adicionado às notas do pedido, e o pedido permanece em espera.
Reembolsos
Os reembolsos não são feitos pelo WooCommerce, por isso não há botão Refund via. Faça o reembolso no back office do Nexi XPay e depois registre-o manualmente no WooCommerce.
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 > Nexi XPay. 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 no vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta no vibefox.net.
Sem uma chave ativa, o Nexi XPay não é exibido aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê Este método de pagamento não está disponível. Escolha outro. Os gerentes da loja logados 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. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e pagamentos adiados ainda podem ser capturados.
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 Nexi XPay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o modo atual tem as duas credenciais (Test Alias e Test MAC Key no modo de teste, Live Alias e Live MAC Key no modo de produção) e se a moeda da loja ou do pedido é EUR. A página de configurações mostra um aviso nesses casos.
O pagamento foi feito, mas o pedido continua Aguardando pagamento: nem a notificação nem o retorno do cliente foram aceitos. Verifique se a loja está acessível pela internet, se a chave MAC e o alias correspondem ao ambiente (teste ou produção) do pagamento, e ative o Debug Log para ver o que o Nexi enviou em WooCommerce > Status > Logs, origem wcp_nexi_gateway.
A notificação responde invalid_mac ou invalid_alias: a chave MAC ou o alias nas configurações não correspondem ao terminal que enviou o resultado. Copie-os novamente da área de teste ou do back office do Nexi.
A notificação responde unknown_transaction: o código de transação não foi emitido por esta loja para aquele pedido. O resultado é ignorado.
A notificação responde not_configured ou busy: o alias ou a chave MAC do ambiente do pagamento está vazio, ou outra requisição estava atualizando o pedido naquele momento. O Nexi tenta a notificação novamente.
O pedido está Em espera após o pagamento: leia a nota do pedido. A captura adiada está selecionada (capture o pagamento com a ação do pedido), o valor ou a moeda não correspondiam, chegou um pagamento para um pedido cancelado, o pagamento está pendente no Nexi, ou Em espera está selecionado como status após o pagamento.
Capture Nexi XPay payment está ausente ou falha: a ação só aparece para pedidos do Nexi em espera como autorizados com captura adiada. Se falhar, leia o erro nas notas do pedido; a captura usa as chaves do ambiente em que o pagamento foi feito.
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 no 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 da licença deste plugin são sempre removidos. As configurações do gateway e os logs são removidos somente se Delete Data on Uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Nexi e XPay são marcas registradas de seus respectivos proprietários. Este plugin não é afiliado nem endossado pelo Nexi.