VibeFox Nexi XPay for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e superiores (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: o cliente precisa finalizar a compra em EUR, então a moeda EUR deve estar habilitada em System > Localisation > Currencies. Para outras moedas, a forma de pagamento fica oculta 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 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, do back office do Nexi XPay depois que a conta de comerciante é ativada. Não há nada a configurar no back office da Nexi: os endereços de retorno e de notificação são enviados com cada pagamento.

Loja pública: a URL de notificação precisa estar acessível pela internet, sem autenticação básica nem regra de firewall que bloqueie a Nexi. Se a notificação não conseguir chegar à loja, o pagamento ainda assim é 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

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém README.txt, o pacote do OpenCart 3 wcp_nexi_gateway-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_nexi_gateway.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_nexi_gateway-oc3-(version).ocmod.zip. A extensão não possui modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Nexi XPay Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa da permissão para modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja a seção Chave de licença).

4. Mantenha Test Mode ativado e informe o alias de teste e a chave MAC de teste (veja Configuração).

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

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_nexi_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Nexi XPay Gateway, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença, os aliases e as chaves MAC como nos passos 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL de notificação é diferente (veja Notification URL).

Uma instalação nova começa com a forma de pagamento desativada e o modo de teste ativado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Nexi XPay Gateway > Edit. As seções são listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, 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 ativado. Ela avisa quando o gateway está ativado, mas o alias ou a chave MAC do modo atual está vazio (a forma de pagamento fica então oculta na finalização de compra), e quando a moeda padrão da loja não é EUR (a forma de pagamento então só é exibida para clientes que finalizam a compra em EUR). Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode ter mais de 128 caracteres, Sort Order deve ser um número inteiro, Total um número igual ou maior que 0, e a zona geográfica e os status do pedido precisam existir; se algum deles estiver incorreto, nada é salvo. Espaços em volta de aliases e chaves colados são removidos.

Nexi XPay

Enable/Disable: Enable Nexi XPay Gateway ativa ou desativa a forma de pagamento. Padrão: desativado.

Title: o título da forma de pagamento exibido ao cliente na finalização de compra. Ele também é o nome da forma de pagamento gravado no pedido. Padrão: Credit Card (Nexi); um título vazio usa o padrão. Até 128 caracteres. No modo de teste, a finalização de compra e o pedido acrescentam (TEST MODE) ao título; um título muito longo é encurtado para que o nome com (TEST MODE) caiba nos 128 caracteres do pedido.

Description: o texto exibido ao cliente na etapa Confirm Order. Padrão: Pay securely with your credit card via Nexi XPay.

Sort Order: a posição do Nexi XPay entre as formas de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: oferece o Nexi XPay somente para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o valor total da compra, na moeda padrão da loja, que um pedido precisa atingir para que o Nexi XPay seja oferecido. Deixe em branco para oferecê-lo para qualquer total.

Ambiente de teste

Os pagamentos de teste vão para int-ecommerce.nexi.it e nunca cobram cartões reais. Obtenha o alias de teste e a chave MAC de teste na área de testes do Nexi XPay ou no portal de desenvolvedores (developer.nexi.it, com link na seção).

Test Mode: usa o ambiente de teste do Nexi XPay e as credenciais de teste. Desative-o para receber pagamentos reais com as credenciais de produção. Padrão: ativado. Enquanto estiver ativado, os clientes veem TEST MODE: the payment goes to the Nexi XPay test environment, no real money is charged. na etapa Confirm Order.

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

As chaves MAC salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-la. Para remover uma chave salva, marque Clear the saved MAC key on save abaixo do campo e clique em Save.

Pagamento

Notification URL: exibida como referência. No OpenCart 3 ela tem a aparência de https://your-store/index.php?route=extension/payment/wcp_nexi_gateway/s2s&nexi_order={order_id}, no OpenCart 4, de https://your-store/index.php?route=extension/wcp_nexi_gateway/payment/wcp_nexi_gateway.s2s&nexi_order={order_id}, com o número do pedido no final, e é montada a partir do endereço da loja da sua instalação do OpenCart. Ela é enviada à Nexi com cada pagamento, então nada precisa ser configurado no back office da Nexi. A Nexi envia o resultado do pagamento para essa URL de servidor a servidor e também o transmite 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, com o alias desse ambiente e com o código de transação emitido para aquele pedido. Resultados que não passam na verificação são rejeitados e não alteram nada.

Capture: quando o valor é cobrado.

Order Status After Payment: o status do pedido depois de um pagamento bem-sucedido. Os status do OpenCart usados em cada opção são definidos na seção Orders.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente, missing order). Ele só recebe um status a partir de um resultado verificado da Nexi. Cada campo abaixo lista os seus status de pedido do OpenCart. O OpenCart não tem o status On hold: por padrão é usado Pending e uma observação do pedido explica o motivo. Você pode criar seus próprios status em System > Localisation > Order Statuses e selecioná-los aqui.

Status: Processing: usado quando Order Status After Payment é Processing. Padrão: Processing.

Status: Completed: usado quando Order Status After Payment é Completed. Padrão: Complete.

Status: awaiting payment: a Nexi informa o pagamento como pendente (esito PEN). Padrão: Pending.

Status: on hold: divergência de valor ou moeda, pagamento recebido para um pedido cancelado, captura adiada (autorizado, ainda não capturado) ou Order Status After Payment definido como On hold. Padrão: Pending.

Status: payment failed: um pagamento pendente que depois falhou. Padrão: Failed.

Status of cancelled orders: o status que a sua loja usa para pedidos cancelados. Um pagamento recebido para um pedido assim é colocado em espera, nunca marcado como pago. A extensão apenas lê este status e nunca o define. Padrão: Canceled.

Avançado

Debug Log: registra os eventos de pagamento em nexi_ip_debug.log.php, na pasta de logs do OpenCart (storage/logs). 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 verificação MAC com falha, são sempre registrados, mesmo quando a opção está desativada. 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: quando ativado, desinstalar a extensão remove as configurações do gateway e o log. Os registros de pagamento do Nexi XPay dos pedidos são sempre mantidos. Padrão: desativado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As chaves MAC não são exportadas.

Import: cole o JSON exportado e clique em Import para restaurar as configurações. As chaves MAC salvas não são alteradas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe a forma de pagamento (por padrão, Credit Card (Nexi)). No OpenCart 4, o cliente a escolhe pelo botão Choose no bloco da forma de pagamento, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização de compra. Na etapa Confirm Order, o cliente vê a sua descrição. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a página mostra Redirecting to the Nexi XPay payment page... e Please do not close this window. e envia o cliente automaticamente à página do Nexi XPay após um segundo, com um botão Pay with Nexi XPay como alternativa. O pagamento é enviado em EUR pelo total do pedido, 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 da sua loja. A página da Nexi abre no idioma da loja do cliente quando é 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 à sua loja. O pedido só é marcado como pago depois de um resultado verificado da Nexi com o valor e a moeda exatos do pedido: vindo da notificação de servidor a servidor ou do retorno assinado do cliente, o que chegar primeiro. Em seguida, o pedido recebe o status da forma padrão do OpenCart, com o e-mail habitual de pedido e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart com Your Nexi XPay payment has been received. Se a 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), mostra Your Nexi XPay payment has been received and is being reviewed. We will contact you if anything is needed.

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

Se o pagamento for recusado, um pagamento pendente falhar ou o cliente cancelar na página da 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. No OpenCart 4, essas mensagens aparecem acima da página de finalização de compra. Um pedido sem status continua sem status e o carrinho é mantido, para que o cliente possa pagar novamente. O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida, e o OpenCart 4 mantém um único pedido para a finalização e paga o mesmo pedido de novo com um novo código de transação. Quando outro pedido do mesmo carrinho já está pago, aguardando pagamento ou em espera, o cliente vai para a página de sucesso em vez de um novo pagamento.

No OpenCart 4, o pedido fica na finalização de compra até que a página de sucesso seja exibida. Se esse pedido foi fechado sem pagamento nesse meio tempo (por exemplo, um pagamento pendente falhou, ou você o cancelou), o cliente volta à finalização de compra com a mensagem Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., também quando volta da Nexi, e o próximo clique em Confirm Order paga um novo pedido. Se o pedido foi pago e depois fechado pela loja (por exemplo, reembolsado), a mensagem é Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order. Se o pedido da finalização já foi feito e o carrinho mudou desde então, a mensagem é Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. Uma alteração do carrinho, incluindo uma nova quantidade, conta como um novo carrinho que precisa do seu próprio pagamento.

Se a extensão não estiver configurada para o modo atual, o cliente vê This payment method is not available right now. Please choose another payment method.

A notificação também funciona enquanto a loja está em modo de manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização para isso, que também deixa passar o retorno do cliente da Nexi.

A extensão recebe pagamentos somente na página do Nexi XPay. Ela não tem reembolsos pelo OpenCart, nem cartões salvos ou OneClick, nem assinaturas ou pagamentos recorrentes, nem Pay-By-Link, nem campos incorporados do XPay Build, nem escolha de formas de pagamento no OpenCart: a página da Nexi mostra as formas habilitadas no seu terminal.

Pedidos e reembolsos

Status do pedido

No status (missing order): o cliente foi enviado à Nexi e não pagou, cancelou ou o pagamento foi recusado, ou a Nexi ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Status: Processing, Completed or on hold: a Nexi confirmou o pagamento. O status segue Order Status After Payment. Uma observação mostra o código de autorização, o código de transação, a bandeira do cartão e a mensagem da Nexi.

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

Status: awaiting payment: a Nexi informou o pagamento como pendente de confirmação. O pedido é atualizado pelo resultado final.

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

Status: payment failed: um pagamento pendente falhou.

Um pedido pago nunca é rebaixado por uma falha posterior. Se outro pagamento bem-sucedido chegar para um pedido que já está pago, ou para outro pedido do mesmo carrinho, uma observação no pedido pago pede que você o reembolse no back office do Nexi XPay caso seja um duplicado; o segundo pedido não é marcado como pago. Quando um pagamento pendente depois dá certo ou falha, o OpenCart notifica o cliente sobre o novo status.

As observações são entradas do History do pedido que o cliente não vê.

Aba VibeFox Nexi XPay Gateway

Em Sales > Orders, abra um pedido pago com o Nexi XPay. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Nexi XPay Gateway mostra o código de transação (codTrans) com o rótulo Test environment nos pagamentos de teste, o status e o resultado da Nexi, o modo e o estado da captura, o valor enviado à Nexi e o valor recebido, o código de autorização, a bandeira do cartão, a mensagem da Nexi, a data e as Nexi XPay notes do pedido. A aba é exibida aos usuários que têm acesso à extensão.

Captura adiada

Para um pedido autorizado em espera, clique em Capture Nexi XPay payment na aba (o botão mostra o valor) e confirme a pergunta Capture the authorized amount through Nexi XPay? Você precisa do direito de modificar a extensão (definido em System > Users > User Groups). A extensão captura o valor autorizado no ambiente do pagamento, com as chaves desse ambiente, e define o status a partir de Order Status After Payment com uma observação. O status é alterado diretamente, como uma mudança manual de status, sem e-mails nem movimentações de estoque. Se a captura falhar, a aba mostra o erro, uma observação é adicionada e o pedido continua em espera. Uma segunda captura do mesmo pagamento é recusada.

Reembolsos

Os reembolsos não são feitos pelo OpenCart, 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 OpenCart. Devoluções de produtos em Sales > Returns não devolvem dinheiro pela Nexi.

Chave de licença

A extensão 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 em Extensions > Extensions > Payments > VibeFox Nexi XPay Gateway > Edit, 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-payment-nexi e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em 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. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê a forma de pagamento na loja, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa pré-visualização não está disponível: a loja não enxerga o login do administrador, então, sem uma chave ativa, a forma de pagamento fica oculta para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. 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, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do painel administrativo: uma vez por dia nos primeiros 14 dias após a chave ser inserida e, depois, uma vez por semana. Não é necessário nenhum cron job. Desinstalar a extensão 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á 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 o cliente finaliza a compra em EUR. A página de configurações mostra um aviso nesses casos. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O pagamento foi aprovado, mas o pedido continua sem status: 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, no campo Log da página da extensão, o que a Nexi enviou.

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 da Nexi.

A notificação responde unknown_transaction ou order_not_found: o código de transação não foi emitido por esta loja para esse pedido, ou o pedido não existe. 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. A Nexi reenvia a notificação.

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

O cliente vê This payment method is not available. Please reload the checkout page.: a sessão de finalização de compra não corresponde mais ao pedido, ou a forma de pagamento foi desativada nesse meio tempo. O cliente recarrega a finalização de compra.

O pedido está no status de espera depois do pagamento: leia as Nexi XPay notes na aba do pedido. A captura adiada está selecionada (capture o pagamento com o botão), o valor ou a moeda não conferiram, chegou um pagamento para um pedido cancelado, ou o Order Status After Payment está definido como On hold.

Capture Nexi XPay payment está ausente ou falha: o botão só é exibido para pedidos do Nexi XPay em espera como autorizados com captura adiada, e somente para usuários que podem modificar a extensão. Se o alias ou a chave MAC do ambiente do pagamento estiverem vazios, a aba informa isso. Se a captura falhar, leia o erro na aba e nas observações, por exemplo Nexi XPay refused the capture com o código e a mensagem da Nexi.

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

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Nexi XPay Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as suas próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status da seção Orders, que voltam aos padrões em uma reinstalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, são removidos também os seus eventos e a sua ação de inicialização, que deixa passar a notificação no modo de manutenção). Se Delete Data on Uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo de teste, aliases, chaves MAC, captura, status do pedido após o pagamento, log de depuração) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação futura. Os registros de pagamento do Nexi XPay dos pedidos (pagamentos, capturas e reembolsos) são sempre mantidos, de modo que pagamentos autorizados ainda podem ser capturados após uma reinstalação. Os pedidos existentes mantêm suas observações de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox Nexi XPay Gateway na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

Nexi e XPay são marcas comerciais de seus respectivos proprietários. Esta extensão não é afiliada nem endossada pela Nexi.