VibeFox Netopia for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior com as extensões OpenSSL, DOM e SimpleXML. O módulo não é instalado sem elas.
Moeda: a moeda do carrinho deve ser RON, EUR, USD ou GBP. EUR, USD e GBP precisam estar habilitadas na sua conta Netopia. Para outras moedas, o meio de pagamento fica oculto na finalização de compra.
Conta Netopia: você precisa de uma conta de vendedor Netopia Payments com um ponto de venda. Nas configurações técnicas dela, você precisa da assinatura da conta e, para cada ambiente que usar (sandbox e produção), do certificado público (.cer) e da chave privada (.key). Não há nada a configurar do lado da Netopia: o endereço da IPN é enviado com cada solicitação de pagamento.
Loja pública: a URL da IPN (confirmação) precisa ser acessível pela internet, sem login ou autenticação básica. Os pedidos só são criados pela IPN da Netopia.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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 encontre depois VibeFox Netopia Gateway na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. No painel da Netopia, abra o seu ponto de venda, copie a assinatura da conta e baixe o certificado e a chave privada dos ambientes sandbox e produção. Cole a assinatura e o conteúdo completo dos arquivos nas configurações (veja Configuração).
5. Ative Enable/Disable e clique em Save. Teste um pagamento no modo sandbox e, em seguida, desative Test mode para receber pagamentos reais.
Na instalação, o módulo cria dois status de pedido, Awaiting Netopia payment e Netopia 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á-los em Payment > Preferences.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Netopia 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 avisa se a assinatura da conta, o certificado ou a chave privada do ambiente ativo estiverem faltando (nesse caso o meio de pagamento fica oculto na finalização de compra) e mostra Test mode is on: payments go to the Netopia sandbox and no real money is charged. enquanto o modo de teste estiver ativo. Ao salvar, um certificado ou uma chave privada inválidos são rejeitados com um erro e o valor anterior é mantido; os demais campos são salvos.
IPN (confirm) URL
Ela aparece somente leitura no topo da página. Com URLs amigáveis, tem este formato: https://your-shop/module/wcp_netopia_gateway/notify, possivelmente com um código de idioma, como /en/. Ela é enviada com cada solicitação de pagamento como URL de confirmação, por isso você não precisa informá-la no painel da Netopia. A Netopia envia a IPN para essa URL. O módulo a descriptografa com a chave privada do ambiente em que o pagamento foi iniciado e verifica a assinatura da sua conta e a solicitação de pagamento. A Netopia informa estas ações:
Uma notificação com um código de erro da Netopia (por exemplo, um cartão recusado) coloca um pedido aguardando em Payment error; sem pedido, o cliente pode pagar de novo. Notificações que não podem ser descriptografadas, que trazem outra assinatura de conta ou que não respondem a uma solicitação de pagamento daquele carrinho são rejeitadas e não alteram nada.
Finalização de compra
Enable/Disable: Enable Netopia Payments ativa ou desativa o meio de pagamento. Padrão: off.
Title: o título do meio de pagamento exibido na finalização de compra. Ele também é o nome do meio de pagamento salvo no pedido. Padrão: Card Payment (Netopia).
Description: a descrição do meio de pagamento exibida na finalização de compra. Padrão: Pay securely with your credit or debit card via Netopia.
Conta Netopia
No painel da Netopia, vá em Seller accounts > your point of sale > Technical settings: copie a assinatura da conta e baixe o certificado público (.cer) e a chave privada (.key) de cada ambiente. Abra os arquivos em um editor de texto e cole todo o conteúdo, incluindo as linhas BEGIN/END.
Account signature: a assinatura da conta de vendedor (formato XXXX-XXXX-XXXX-XXXX-XXXX), a mesma para sandbox e produção.
Test mode: usa o sandbox da Netopia (sandboxsecure.mobilpay.ro) e as chaves do sandbox. Padrão: on. Desative para receber pagamentos reais com as chaves de produção.
Sandbox public certificate (.cer): o conteúdo do arquivo do certificado público do sandbox. Ele é usado para criptografar a solicitação de pagamento.
Sandbox private key (.key): o conteúdo do arquivo da chave privada do sandbox. Ele é usado para descriptografar a IPN.
Live public certificate (.cer): o conteúdo do arquivo do certificado público de produção.
Live private key (.key): o conteúdo do arquivo da chave privada de produção.
As chaves privadas salvas nunca são exibidas novamente. O campo fica vazio, e o texto de ajuda dele começa com A private key is saved. Deixe-o vazio para manter a chave salva ou cole uma nova chave para substituí-la. Um campo de certificado vazio remove o certificado.
Clear saved private keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém a chave salva.
Pedidos
Order status after payment: o status de um pedido pago.
Avançado
Debug log: grava as solicitações e o processamento das IPNs em logs/netopia_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Dados de cartão, chaves e dados de clientes não são registrados. Erros, por exemplo IPNs rejeitadas, são sempre registrados, mesmo com a opção desativada. Padrão: off.
Log: mostra o tamanho e as últimas entradas do registro. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: ao desinstalar o módulo, remove as configurações do gateway, os registros de pagamento Netopia do módulo e o log. Os pedidos são mantidos. Padrão: off.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o meio de pagamento (por padrão, Card Payment (Netopia)) e confirma. A página seguinte mostra Redirecting you to Netopia for secure payment… e envia o cliente automaticamente para a página de pagamento da Netopia, com os botões Proceed to payment e Cancel (volta à finalização de compra) como alternativa. A solicitação de pagamento é criptografada com o seu certificado Netopia e contém o total do carrinho na moeda do carrinho, Cart # com o número do carrinho, e os dados de contato de cobrança e entrega. No modo sandbox, a solicitação vai para o sandbox da Netopia. Nesse ponto, ainda não existe pedido.
O cliente paga com cartão na página da Netopia e volta para a sua loja. O retorno em si nunca cria nem paga um pedido. O pedido só é marcado como pago depois que a Netopia confirma por meio da IPN. Se o pedido existir, o cliente vê a página padrão de confirmação do pedido. Para um pedido aguardando, ela mostra Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. Para um pedido em espera, mostra Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. Para um pedido cancelado, mostra The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time. Para um pedido com erro de pagamento, mostra The payment was declined by Netopia.
Se a IPN ainda não tiver chegado quando o cliente voltar, uma página Payment confirmation mostra o mesmo texto de "ainda não confirmado", com os botões Check again e Back to checkout. O pedido é criado assim que a IPN chegar.
Se a Netopia tiver informado um cancelamento ou uma recusa antes de qualquer pedido ser criado, o cliente volta à finalização de compra com The payment was cancelled at Netopia. You can try again or choose another payment method. ou The payment was declined by Netopia. You can try again or choose another payment method. O carrinho é mantido. Cada nova tentativa é uma nova solicitação de pagamento; as solicitações anteriores do carrinho continuam válidas, então uma IPN atrasada de uma tentativa anterior ainda é registrada.
Se o módulo não estiver configurado corretamente, o cliente permanece na finalização de compra com Netopia gateway is not configured properly. Please contact the store administrator. Outras mensagens são Netopia cannot process payments in seguido da moeda, This order has nothing to pay. e Payment encryption failed. Please try again or contact support. O motivo técnico é gravado no log.
A IPN funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.
O módulo aceita pagamentos com cartão somente pelo protocolo de cartão Netopia v1. Não há reembolsos nem capturas pelo PrestaShop, nem cartões salvos ou pagamentos com um clique, nem assinaturas, parcelamentos ou outros meios de pagamento, e não há suporte à Netopia API v2.
Pedidos e reembolsos
Status do pedido
Ainda sem pedido: o cliente foi enviado à Netopia e ainda não pagou, ou a Netopia ainda não enviou a IPN. Existe apenas o carrinho.
Payment accepted or Delivered: a Netopia confirmou o pagamento. O status segue Order status after payment. O pagamento é registrado com a transação Netopia como ID da transação, e uma nota privada mostra o valor, o número mascarado do cartão e a transação Netopia; pagamentos sandbox são marcados como [sandbox].
Awaiting Netopia payment: o pagamento é uma pré-autorização aguardando captura no painel da Netopia, ou está em análise na Netopia. Nenhum pagamento foi registrado ainda. O pedido passa ao status pago quando a Netopia o confirma.
Netopia payment on hold: o valor ou a moeda da fatura diferem do carrinho ou do pedido, só uma parte do pagamento foi capturada, a Netopia confirmou o pagamento de um pedido cancelado ou de um pedido feito com outro meio de pagamento, ou um pagamento de teste (sandbox) foi confirmado enquanto a loja está em modo de produção (nenhum dinheiro real foi recebido, por isso nenhum pagamento é registrado). A nota explica. Verifique a transação no painel da Netopia e, em seguida, processe o pedido ou reembolse o pagamento por lá.
Payment error: a Netopia informou um erro, por exemplo um cartão recusado, para um pedido aguardando.
Canceled: a Netopia cancelou o pagamento de um pedido aguardando.
Refunded: o pagamento foi reembolsado integralmente no painel da Netopia.
Notificações atrasadas nunca rebaixam um pedido pago ou encerrado. Se a Netopia confirmar outro pagamento para um pedido que já está pago, uma nota pede que você reembolse a duplicata no painel da Netopia.
Bloco da Netopia
A página do pedido mostra um bloco Netopia Payments com a transação Netopia, o ambiente (sandbox ou produção), a solicitação de pagamento, a última ação da IPN, o cartão mascarado, os valores pago, reembolsado e restante, e o histórico de reembolsos. O bloco é somente leitura.
Reembolsos
Os reembolsos não são feitos pelo PrestaShop: o protocolo de cartão Netopia v1 não tem uma chamada de reembolso. Reembolse a transação no painel da Netopia. Em seguida, a Netopia envia uma IPN de crédito, e o módulo registra o reembolso no pedido automaticamente, com a nota Netopia refund processed: e o valor. Um reembolso parcial mantém o status do pedido; quando não resta nada a reembolsar, o pedido passa para Refunded. Para pedidos em EUR, USD e GBP, o valor reembolsado, que a Netopia informa em RON, é convertido de volta para a moeda do pedido. Um reembolso nunca é registrado duas vezes nem por um valor maior que o restante. Se a Netopia informar um erro no reembolso, apenas uma nota é adicionada.
O módulo não cria notas de crédito e não devolve produtos ao estoque. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Netopia.
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 Netopia Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Netopia Gateway > Configure, acima das configurações. Insira a chave no campo 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 estão a linha Product: presta-payment-netopia 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 para o 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, também 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, a Netopia não é exibida 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 os reembolsos feitos no painel da Netopia continuam sendo registrados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: 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 ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Netopia não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o ambiente ativo está completo (Account signature mais o certificado e a chave privada do sandbox no modo de teste, ou os de produção no modo de produção) e se a moeda do carrinho é RON, EUR, USD ou GBP. A página de configurações mostra um aviso quando algo está faltando. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi feito, mas nenhum pedido foi criado: a IPN não chegou à sua loja ou foi rejeitada. Verifique se a URL da IPN (confirmação) indicada nas configurações é acessível pela internet (sem autenticação básica nem firewall). Consulte o campo Log na página do módulo: as IPNs rejeitadas são sempre registradas. Ative o Debug log para ver cada IPN. O simples retorno do cliente nunca cria um pedido.
O log mostra failed decrypting data: a chave privada não corresponde ao certificado que a Netopia usou. A IPN é descriptografada com a chave privada salva de cada ambiente, então mantenha salva a chave do outro ambiente enquanto os pagamentos dele estiverem abertos. A Netopia reenvia a IPN.
O log mostra signature mismatch: a Account signature é diferente do ponto de venda que enviou a IPN. Copie-a novamente do painel da Netopia.
O log mostra unknown payment request: a IPN não responde a uma solicitação de pagamento que a sua loja fez para aquele carrinho naquele ambiente (sandbox ou produção). Nada é alterado.
O log mostra gateway not configured: não há chave privada nem assinatura de conta salva. A Netopia reenvia a IPN, e o pagamento é registrado quando as configurações estiverem completas.
O log mostra busy, retry later or processing failed: o carrinho estava sendo processado por outra solicitação no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Netopia reenvia a IPN automaticamente.
Erro ao salvar sobre o certificado ou a chave privada: o texto colado não é um certificado ou uma chave válidos. Cole o conteúdo completo do arquivo, incluindo as linhas BEGIN/END. O valor anterior foi mantido.
O pedido está em Netopia payment on hold após o pagamento: leia a nota privada do pedido (veja Status do pedido). O valor ou a moeda eram diferentes, só uma parte foi capturada, o pedido tinha sido cancelado, ou um pagamento sandbox foi confirmado enquanto a loja estava em modo de produção. Verifique a transação no painel da Netopia.
Um reembolso feito na Netopia não aparece no pedido: a IPN de crédito não chegou à loja ou foi rejeitada. Verifique o log.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Netopia 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 gateway (incluindo as chaves salvas), os registros de pagamento Netopia do módulo (exibidos no bloco Netopia dos pedidos) e o log são removidos. Se estiver desativado, tudo é mantido para uma reinstalação posterior. Os pedidos e os status Awaiting Netopia payment e Netopia payment on hold nunca são excluídos. Os pedidos existentes mantêm as suas notas de pagamento e IDs de transação.
Netopia Payments e mobilPay são marcas registradas de seus respectivos titulares. Este módulo não é afiliado nem endossado pela Netopia Payments.