VibeFox Nexi XPay 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 anteriores do PHP.

Moeda: a moeda do carrinho deve 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 testes do Nexi XPay ou do portal de desenvolvedores (developer.nexi.it), e as de produção vêm 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 autenticação básica nem regra de firewall que bloqueie o Nexi. O modo de manutenção da loja não a bloqueia. Se a notificação não conseguir chegar à loja, 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 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, depois, encontre VibeFox Nexi XPay Gateway na lista de módulos e clique em Configure.

3. Insira a 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. Mantenha Test Mode ativado e insira o alias e a chave MAC de teste (veja Configuração).

5. Ative Enable/Disable, clique em Save e faça um pedido de teste. Quando tudo estiver funcionando, insira o alias e a chave MAC de produção e desative Test Mode.

Na instalação, o módulo cria dois status de pedido: Awaiting Nexi XPay payment e Nexi XPay 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á-lo em Payment > Preferences. Um país ativado na loja depois da instalação do módulo também precisa ser marcado ali.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Nexi XPay Gateway > 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 go to the Nexi XPay test environment, no real money is charged. enquanto o modo de teste estiver ativo. Ela avisa quando o gateway está ativado, mas o alias ou a chave MAC do modo atual estão vazios, ou quando a moeda padrão da loja não é EUR. Nesses casos, o método de pagamento fica oculto na finalização de compra. Espaços e quebras de linha em volta dos valores colados são removidos ao salvar.

Nexi XPay

Enable/Disable: Enable Nexi XPay Gateway ativa ou desativa o método de pagamento. Padrão: off.

Title: o título do método de pagamento exibido ao cliente na finalização de compra. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Credit Card (Nexi). No modo de teste, a finalização de compra e o pedido acrescentam (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 testes do Nexi XPay ou no portal de desenvolvedores (developer.nexi.it).

Test Mode: usa o ambiente de teste do Nexi XPay e as credenciais de teste. Desative para receber pagamentos reais com as credenciais de produção. Padrão: on.

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 mostrados 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.

Chaves MAC salvas nunca são mostradas novamente. O campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.

Limpar segredos salvos: marque Test MAC Key ou Live MAC Key e clique em Save para remover uma chave salva. Um campo vazio mantém o valor salvo.

Pagamento

Notification URL: exibida apenas para referência. Ela é enviada ao Nexi com cada pagamento, então nada precisa ser configurado no back office do Nexi. Com URLs amigáveis, ela tem esta aparência: https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}, possivelmente com um código de idioma como /it/, e com o número do carrinho no final. O Nexi envia o resultado do pagamento para esta URL de servidor a servidor e também o passa junto com o retorno do cliente. Ambos são assinados da mesma forma e são verificados com a chave MAC do ambiente em que o pagamento foi feito, o alias desse ambiente e o código de transação emitido para esse carrinho. Resultados que não passam na verificação são rejeitados e não alteram nada.

Captura: quando o dinheiro é cobrado.

Order Status After Payment: o status do pedido após um pagamento bem-sucedido.

Avançado

Debug Log: registra os eventos de pagamento em logs/nexi_ip_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves MAC, MACs, dados de cartão e endereços de e-mail não são registrados. Erros e avisos, por exemplo uma falha na verificação MAC, são sempre registrados, mesmo com a opção desligada. Padrão: off.

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

Delete Data on Uninstall: quando ativada, desinstalar o módulo remove todas as configurações do módulo e o registro. Os dados de pagamento do Nexi XPay dos pedidos e os status dos pedidos são mantidos. Padrão: off.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Credit Card (Nexi)) e confirma. A página seguinte mostra Redirecting to Nexi XPay for payment... 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 pelo total do carrinho, com um novo código de transação, o e-mail do cliente, a descrição Cart, o número do carrinho e o nome da sua loja. A página do Nexi abre no idioma do carrinho quando ele é italiano, inglês, espanhol, francês, alemão, japonês, chinês, árabe, russo ou português; caso contrário, em inglês. Nenhum pedido existe ainda nesse ponto.

O cliente paga e volta para a sua loja. O pedido só é marcado como pago depois de um resultado verificado do Nexi com o valor e a moeda exatos do carrinho: vindo da notificação servidor a servidor ou do retorno assinado do cliente, o que chegar primeiro. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your Nexi XPay payment has been received. Se o Nexi informar que o pagamento está pendente, a página mostra Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. Para um pedido em espera (captura adiada ou revisão manual), ela mostra We have received your Nexi XPay payment authorization. Your order will be processed shortly. Se um pagamento pendente falhar depois, a página mostra The payment was not completed. Please contact us.

Se o resultado ainda não tiver sido processado quando o cliente voltar, aparece uma página com We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. e um botão Check again. A notificação cria o pedido assim que chega.

Se o pagamento for recusado ou o cliente cancelar na página do Nexi, ele volta à finalização de compra e vê uma destas mensagens: The payment was not completed. Please try again or choose a different payment method., Payment was cancelled. Please try again. ou We could not confirm the payment. If your card was charged, please contact us before paying again. Nenhum pedido é criado e o carrinho é mantido, para que o cliente possa pagar de novo. Se o carrinho já tiver um pedido (por exemplo, foi pago em outra aba), o cliente vai para a confirmação do pedido em vez de um novo pagamento.

Se o módulo não estiver configurado para o modo atual, o cliente vê This payment method is not available right now. Please choose another payment method.

A notificação funciona enquanto a loja estiver em modo de manutenção e não é bloqueada pela restrição de países da sua loja.

O módulo recebe pagamentos somente na página do Nexi XPay. Não há reembolsos pelo PrestaShop, cartões salvos ou OneClick, assinaturas ou pagamentos recorrentes, Pay-By-Link, campos incorporados do XPay Build, nem métodos de pagamento selecionados no PrestaShop: a página do Nexi mostra os métodos ativados no seu terminal.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado ao Nexi e não pagou, cancelou ou teve o pagamento recusado, ou o Nexi ainda não confirmou o pagamento. Só o carrinho existe.

Payment accepted, Delivered or Nexi XPay payment on hold: o Nexi confirmou o pagamento. O status segue Order Status After Payment. O pagamento é registrado com o código de transação do Nexi como ID da transação, e uma nota mostra o código de autorização, o código de transação, a bandeira do cartão e a mensagem do Nexi.

Nexi XPay payment on hold (authorized): a captura adiada está selecionada e o pagamento está apenas autorizado. Capture-o com Capture Nexi XPay payment na página do pedido.

Awaiting Nexi XPay payment: o Nexi informou que o pagamento aguarda confirmação. O pedido é atualizado pelo resultado final.

Nexi XPay payment on hold after payment: o valor ou a moeda recebidos do Nexi não correspondiam ao carrinho (o pedido não é marcado como pago), ou chegou um pagamento bem-sucedido para um pedido que já tinha sido cancelado. A nota explica. Verifique o pagamento no back office do Nexi XPay e processe ou reembolse o pedido.

Erro de pagamento: um pagamento pendente falhou. O mesmo carrinho não pode ser pago de novo, então o cliente precisa fazer um novo pedido.

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.

Bloco de pagamento do Nexi XPay

A página do pedido mostra um bloco Nexi XPay payment com o código de transação (codTrans), o status e o resultado do Nexi, o modo de captura, o valor enviado ao Nexi e o valor recebido, o código de autorização, a bandeira do cartão, a mensagem do Nexi e a data, um selo Test environment para pagamentos de teste e as Nexi XPay notes do pedido.

Captura adiada

Para um pedido autorizado em espera, clique em Capture Nexi XPay payment no bloco (o botão mostra o valor) e confirme a pergunta Capture the authorized amount through Nexi XPay? Você precisa ter permissão para editar pedidos. O módulo captura o valor autorizado no ambiente do pagamento, com as chaves desse ambiente, registra o pagamento e define o status de acordo com Order Status After Payment. Se a captura falhar, o bloco mostra o erro, uma nota é adicionada e o pedido permanece em espera. Uma segunda captura do mesmo pagamento é recusada.

Reembolsos

Os reembolsos não são feitos pelo PrestaShop, então não há botão de reembolso para o Nexi XPay. Faça o reembolso no back office do Nexi XPay e depois registre-o manualmente no PrestaShop. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pelo Nexi.

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 Nexi XPay Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Nexi XPay 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-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, o Nexi XPay não é exibido 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 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 pagamentos autorizados ainda podem ser capturados.

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

O Nexi XPay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, 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 do carrinho é EUR. A página de configurações mostra um aviso nesses casos. Em Payment > Preferences, verifique se o módulo está permitido para EUR, para o país do cliente e para o grupo do cliente.

O pagamento foi feito, mas nenhum pedido foi criado: 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 Debug Log para ver o que o Nexi enviou no campo Log da página do módulo.

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 testes 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 esse carrinho. O resultado é ignorado.

A notificação responde not_configured ou busy: o alias ou a chave MAC do ambiente do pagamento estão vazios, ou o pedido estava sendo atualizado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). O Nexi tenta a notificação novamente.

A URL de notificação mostra method_not_allowed no navegador: isso é normal. A URL aceita somente requisições do Nexi.

O pedido está em Nexi XPay payment on hold after payment: leia as Nexi XPay notes no bloco do pedido. A captura adiada está selecionada (capture o pagamento com o botão), o valor ou a moeda não correspondiam, um pagamento chegou para um pedido cancelado, ou Nexi XPay payment on hold está selecionado como status após o pagamento.

Capture Nexi XPay payment está ausente ou falha: o botão só aparece em pedidos do Nexi XPay que estão em espera como autorizados com captura adiada, e somente para funcionários que podem editar pedidos. Se o alias ou a chave MAC do ambiente do pagamento estiverem vazios, o bloco informa. Se a captura falhar, leia o erro no bloco e nas notas, por exemplo Nexi XPay refused the capture com o código e a mensagem do Nexi.

Pagamentos de teste não confirmam um pagamento real: cada pagamento é verificado com as chaves do ambiente em que foi iniciado. Altere Test Mode para o modo desejado e use o alias e a chave MAC desse modo.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Nexi XPay 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 registro são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados de pagamento do Nexi XPay dos pedidos e os status de pedido Awaiting Nexi XPay payment e Nexi XPay payment on hold são sempre mantidos, para que pagamentos autorizados possam ser capturados depois de uma reinstalação. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Nexi e XPay são marcas registradas de seus respectivos titulares. Este módulo não é afiliado nem endossado pelo Nexi.