VibeFox Nets Nexi for OpenCart — Ajuda

Requisitos

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

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 formas de pagamento: a extensão não restringe moedas por conta própria. Use as moedas habilitadas na sua conta Nets; uma moeda não suportada é informada pela Nets quando o pagamento é criado. Quais formas 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 com no máximo 256 caracteres e sem "&", portanto sua loja precisa de HTTPS para receber webhooks. Sem HTTPS, 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

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote para OpenCart 3 wcp_nets_nexi_gateway-oc3-(versão).ocmod.zip e o pacote para OpenCart 4 wcp_nets_nexi_gateway.ocmod.zip. Instale somente 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_nets_nexi_gateway-oc3-(versão).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 Nets Nexi 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. Copie a chave secreta de teste do portal de testes da Nets Easy e cole-a em Test Secret Key (veja Configuração). Não é preciso configurar nada no portal da Nets.

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.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_nets_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 Nets Nexi 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 e as chaves secretas como nos passos 3 a 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só o endereço do webhook é diferente (veja Webhooks).

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 Nets Nexi 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 avisa quando a chave secreta do modo selecionado está ausente, por exemplo 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. 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 estar vazio (até 128 caracteres), Sort Order deve ser um número inteiro, Total deve ser um número igual ou maior que 0, e a zona geográfica e os status do pedido precisam existir; se algum campo estiver incorreto, nada é salvo.

Nets Nexi (países nórdicos)

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

Title: o título da forma de pagamento exibido aos clientes durante o checkout. Ele também é o nome da forma de pagamento gravado no pedido. Padrão: Nets Easy. Obrigatório.

Description: o texto exibido ao cliente na etapa Confirm Order. Padrão: Pay securely with Nets Easy.

Sort Order: a posição da Nets entre as formas de pagamento no checkout. Deixe em branco ou informe um número inteiro.

Geo Zone: oferece a Nets 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 do carrinho, na moeda padrão da loja, que um pedido precisa atingir para que a Nets seja oferecida. Deixe em branco para oferecer a Nets para qualquer valor total.

Chaves de API

Copie as chaves secretas do portal da 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. A seção traz links para os dois portais. 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. na etapa Confirm Order.

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 mostradas novamente. O campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la. Para remover uma chave salva, marque Clear the saved key on save abaixo do campo e clique em Save.

Pagamento

Webhooks: as notificações da Nets (webhooks) são registradas automaticamente a cada pagamento. Não há nada a configurar no portal da Nets. O campo mostra o endereço para o qual elas são enviadas. No OpenCart 3 ele tem a aparência de https://your-store/index.php?route=extension/payment/wcp_nets_nexi_gateway/webhook, e no OpenCart 4, de https://your-store/index.php?route=extension/wcp_nets_nexi_gateway/payment/wcp_nets_nexi_gateway.webhook. Ele é montado a partir do endereço da loja da sua instalação do OpenCart. Se não for um endereço HTTPS público, o campo 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 conter o segredo aleatório que a extensão criou para aquele pagamento. Webhooks sem o segredo correto são rejeitados. O webhook apenas informa à extensão qual pagamento mudou: o pagamento em si é sempre lido da API da Nets com a chave secreta do ambiente em que foi feito.

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente, missing order). Ele só recebe um status depois que o pagamento é lido de volta da API da Nets (webhook, retorno do cliente ou Nets: check payment status and capture na página do pedido) e uma reserva correspondente é cobrada. Cada campo de status abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status do pedido depois que a Nets confirma e cobra o pagamento. Padrão: Processing. Escolha Complete para marcar os pedidos pagos como concluídos.

Nets Payment On Hold Status: o valor ou a moeda diferem do pedido, a captura falhou ou o cliente pagou depois que o pedido foi cancelado. Nada é capturado automaticamente, e uma observação explica o motivo. Padrão: Pending, porque o OpenCart não tem um status On hold. Você pode criar seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Cancelled Status: definido quando a reserva do pedido é cancelada no portal da Nets. Padrão: Canceled.

Refunded Status: definido depois que o pagamento é totalmente reembolsado pela página do pedido. Padrão: Refunded.

Avançado

Debug log: registra chamadas de API e mudanças de status de pagamento em nng_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Chaves e dados dos clientes não são registrados. Erros e avisos 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 e reembolso da Nets dos pedidos são sempre mantidos. Padrão: desativado.

Importar / Exportar

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

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves secretas salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe a forma de pagamento (por padrão, Nets Easy). Na etapa Confirm Order, o cliente vê a sua descrição e a observação You will be redirected to the Nets payment page to pay securely. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria um pagamento na Nets pelo total do pedido na moeda do pedido, com os produtos, o frete e os demais totais do pedido (cupons, vales, taxas) como itens do pedido, e envia o cliente à página de pagamento hospedada pela Nets. No OpenCart 4 o cliente escolhe a forma de pagamento com o botão Choose do 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. A referência do pagamento na Nets é o número do pedido do OpenCart. O e-mail, o nome, o endereço de entrega e o telefone do cliente são enviados à Nets quando ela aceita o formato. A página de termos de compra da sua loja é linkada na página da Nets (se não houver, a página inicial da loja).

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Nets confirma: a extensão lê o pagamento da API da Nets, compara o valor e a moeda reservados com o pedido, cobra a reserva e só então define o status do pedido. Isso acontece pelo webhook ou quando o cliente retorna, o que ocorrer 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. Se o pagamento ainda não puder ser confirmado (a Nets não estava acessível, ou outra requisição estava confirmando naquele momento), uma página Payment confirmation mostra Your Nets payment is being confirmed. Your order will be updated 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, ele volta ao checkout com The Nets payment was cancelled. You can try again or choose another payment method. Se nada tiver sido pago, a mensagem é The payment was not completed. You can try again or choose another payment method. No OpenCart 4 essas mensagens aparecem acima da página de finalização de compra. O carrinho é mantido. O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida, enquanto o OpenCart 4 mantém um único pedido para a finalização de compra e paga o mesmo pedido novamente com um novo pagamento na Nets. Em uma nova tentativa, a extensão primeiro verifica os pagamentos anteriores do carrinho; se um deles já estiver pago, esse pedido é confirmado em vez de iniciar um novo pagamento. Caso contrário, as sessões anteriores da Nets são encerradas antes de iniciar uma nova. Quando outro pedido do mesmo carrinho já estiver pago ou em espera, o cliente vai para a página de sucesso.

No OpenCart 4 o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado sem pagamento nesse meio tempo (por exemplo, se você o cancelou, inclusive depois de cancelar a reserva no portal da Nets), o cliente é enviado de 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 retorna da Nets, e o próximo clique em Confirm Order paga um novo pedido. Um pedido do carrinho que foi pago e depois cancelado ou reembolsado não mantém mais o carrinho.

Se a Nets não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order 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 pedido igual a zero gera The order total must be greater than zero to pay with Nets. Os detalhes são gravados no log.

O webhook também funciona enquanto a loja está em modo de manutenção, porque 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 (startup) para isso, que também permite ao cliente voltar da Nets.

A extensão usa somente a página de pagamento hospedada. Ela não tem checkout Nets integrado na própria página, nem assinaturas ou pagamentos recorrentes, nem cartões salvos, nem taxas de fatura, nem modo somente autorização, nem capturas parciais por remessa.

Pedidos e reembolsos

Status do pedido

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

Order Status After Payment (default Processing): a Nets confirmou e cobrou o pagamento. Uma observação mostra o ID do pagamento, o ID da cobrança e a forma de pagamento.

Nets Payment On Hold Status (default Pending): 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 observação 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.

Cancelled Status (default Canceled): a reserva do pedido foi cancelada, por exemplo no portal da Nets.

Refunded Status (default Refunded): o pagamento foi totalmente reembolsado pela extensão.

Quando um webhook ou o retorno do cliente move um pedido do status de retenção para o status pago, ou o cancela, o OpenCart notifica o cliente. Webhooks repetidos e recarregamentos da página nunca cobram duas vezes nem adicionam observações duplicadas, e um pedido pago nunca é alterado novamente por eventos da Nets. Se um link de pagamento antigo for concluído para um pedido que já está pago, ou para outro pedido do mesmo carrinho, a segunda reserva é liberada automaticamente; se ela já tiver sido cobrada, uma observação pede que você a reembolse no portal da Nets. Se o pedido foi marcado como pago de outra forma, um pagamento reservado na Nets não é capturado e uma observação informa isso.

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

Aba VibeFox Nets Nexi Gateway

Em Sales > Orders, abra um pedido pago com a Nets. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Nets Nexi Gateway mostra o bloco Nets Easy payment: o ID do pagamento, o ID da cobrança, o ambiente (com o rótulo Test environment nos pagamentos de teste), o status e a forma de pagamento, os valores reservados e cobrados na Nets, o total do pedido e o valor reembolsado, o formulário de reembolso, o histórico de reembolsos e as Nets notes do pedido. A aba é exibida aos usuários que têm acesso à extensão; os botões dela exigem a permissão para modificar a extensão (definida em System > Users > User Groups).

Nets: check payment status and capture: exibido para pedidos que ainda não foram pagos. Ele lê o pagamento na Nets e captura uma reserva que corresponda ao pedido, inclusive depois de uma captura com falha ou depois que você revisou um pedido em retenção. Se nada mudar, uma observação explica o motivo, por exemplo que o cliente ainda não concluiu o pagamento. Um status definido por este botão, assim como um status definido por um reembolso, é alterado diretamente, como uma mudança manual de status, sem e-mails nem movimentações de estoque.

Reembolsos

Na aba, informe o Amount (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional), 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 é cobrado, até o total do pedido; um pagamento apenas reservado pode ser cancelado no portal da Nets. O reembolso vai para a cobrança do pedido no ambiente em que o pagamento foi feito, por isso a chave secreta desse ambiente precisa estar definida. Se a Nets não aceitar o reembolso, a aba mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às observações, com o ID do reembolso da Nets. Um reembolso total define o pedido como Refunded Status; um reembolso parcial não altera o status.

Devoluções de produtos em Sales > Returns 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

A extensão 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 em Extensions > Extensions > Payments > VibeFox Nets Nexi 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-nets-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, a Nets não é exibida aos clientes no checkout. 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 visualização não está disponível: a loja não vê 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 os reembolsos funcionam.

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

A Nets Nexi não aparece no checkout: 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. 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: o webhook não chegou à sua loja. Verifique se a loja usa HTTPS, de modo que o endereço em Webhooks seja um endereço HTTPS público, e se a chave secreta do ambiente do pagamento está definida. O pedido também recebe o status quando o cliente volta à loja após pagar, ou com Nets: check payment status and capture na aba do pedido.

O webhook responde Unauthorized: o webhook não trouxe o segredo daquele pagamento. Os webhooks só são aceitos com o segredo registrado junto ao pagamento.

O webhook responde Unknown payment: o pagamento não foi criado por esta loja.

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 pôde ser acessada, ou a reserva ainda não estava visível. A Nets tenta o webhook novamente automaticamente.

O webhook responde Order could not be updated, retry later: não foi possível definir o status do pedido. A Nets tenta o webhook novamente. Ative o Debug log para ver o motivo.

A URL do webhook mostra Method not allowed no navegador: isso é normal. O endereço aceita somente requisições da Nets.

O cliente vê um erro depois de Confirm Order: ative o Debug log e veja o campo Log na página da extensão. This payment method is temporarily unavailable. Please choose another payment method. geralmente indica uma chave secreta incorreta ou ausente. Uma moeda recusada é informada pela Nets no log. This payment method is not available. significa que a sessão do checkout não corresponde mais ao pedido, ou que a forma de pagamento foi desativada nesse meio tempo: o cliente recarrega o checkout.

O cliente vê We could not match this payment to an order: o link de retorno está incompleto ou pertence a outro pedido. Se o cliente foi cobrado, procure o pagamento no portal da Nets e verifique o pedido.

O pedido está no status de retenção depois do pagamento: leia as Nets notes na aba. Se a captura foi recusada, tente novamente com Nets: check payment status and capture ou cobre o pagamento no portal da Nets. Se o valor ou a moeda não conferirem, verifique o pagamento no portal da Nets. Se o cliente pagou depois do cancelamento, revise o pedido e capture ou cancele a reserva.

Refund via Nets está ausente ou falha: reembolsos só são possíveis depois que o pagamento foi cobrado; a aba 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, a aba informa qual chave de ambiente está faltando.

Para desenvolvedores: antes de o pagamento ser criado, a extensão dispara o evento do OpenCart nng_create_payment_payload com o corpo da requisição e o pedido; nng_currency_decimals altera as casas decimais de uma moeda.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Nets Nexi 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 de pedido da seção Payment, que voltam aos padrões em uma reinstalação. No OpenCart 4, também são removidos os eventos da extensão e a sua ação de inicialização, que deixa passar o webhook 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, chaves secretas, log) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação futura. Os dados de pagamento da Nets dos pedidos (pagamentos, cobranças e reembolsos) são sempre mantidos, de modo que pedidos pagos antes ainda podem ser reembolsados 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 e clique em Uninstall (o botão laranja −) ao lado de VibeFox Nets Nexi Gateway na lista de extensões instaladas, depois em Delete (o botão vermelho da lixeira) para remover o pacote enviado.

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