VibeFox Netopia for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo.

PHP: 8.0 ou superior com as extensões OpenSSL e DOM.

Moeda: a moeda da loja ou do pedido deve ser RON, EUR, USD ou GBP. EUR, USD e GBP precisam estar habilitadas na sua conta Netopia. Para outras moedas, o método de pagamento fica oculto na finalização de compra.

Conta Netopia: você precisa de uma conta de vendedor da 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 (teste e produção), do certificado público (.cer) e da chave privada (.key). Não é preciso configurar nada no lado da Netopia: o endereço da IPN é enviado com cada solicitação de pagamento.

Site público: a URL da IPN (confirmação) precisa estar acessível pela internet, sem estar atrás de login, de autenticação básica ou de uma página de manutenção. Os pedidos são atualizados somente pela IPN da Netopia.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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_netopia_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Netopia Payments > Manage, ou clique em Settings embaixo do nome do plugin na página Plugins.

4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. 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 de teste e de produção. Cole a assinatura e o conteúdo completo dos arquivos nas configurações (veja Configuração).

6. Ative Enable/Disable. Teste um pagamento no modo de teste e, depois, desmarque Test mode para receber pagamentos reais.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Netopia Payments. Acima dos campos, a página avisa quando a assinatura da conta, o certificado ou a chave privada do ambiente ativo estão ausentes (o método 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. Na lista de métodos de pagamento, a Netopia aparece como pendente de configuração até que o ambiente ativo esteja completo. Ao salvar, um certificado ou uma chave privada inválidos são rejeitados com um erro, e o valor anterior é mantido.

IPN (confirm) URL

Exibida somente para leitura no topo das configurações. Tem este formato: https://your-site/wc-api/netopia_payment_callback/. Ela é enviada com cada solicitação de pagamento como URL de confirmação, então você não precisa informá-la no painel da Netopia. A Netopia envia a IPN para essa URL; o plugin a descriptografa com a chave privada do ambiente ativo 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) marca um pedido não pago como falho. 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 pedido são rejeitadas e não alteram nada.

Finalização de compra

Enable/Disable: Enable Netopia Payments ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o título do método de pagamento exibido na finalização de compra. Padrão: Card Payment (Netopia).

Description: a descrição do método 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, acesse 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 o conteúdo completo, incluindo as linhas BEGIN/END.

Account signature: a assinatura da conta de vendedor (formato XXXX-XXXX-XXXX-XXXX-XXXX), a mesma para teste e produção.

Test mode: Use the Netopia sandbox (sandboxsecure.mobilpay.ro) and the sandbox keys. Alterna a página de pagamento e o par de chaves. Padrão: ativado. 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. Depois de salvo, nunca é exibido novamente; o campo mostra A private key is saved. Deixe-o vazio para manter a chave salva, ou cole uma nova chave para substituí-la.

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. Depois de salvo, nunca é exibido novamente; deixe o campo vazio para manter a chave salva.

Pedidos

Order status after payment: o status de um pedido pago que precisa ser enviado. Pedidos com apenas itens virtuais ou para download são concluídos pelo WooCommerce de qualquer forma. O status é definido com uma única mudança de status e um único e-mail ao cliente.

Avançado

Debug log: Log requests and IPN processing grava em WooCommerce > Status > Logs, origem wcp_netopia_gateway. 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: desativado.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (orders are kept). Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Card Payment (Netopia)) e faz o pedido. 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 order como alternativa. A solicitação de pagamento é criptografada com o seu certificado Netopia e contém o total do pedido na moeda do pedido, Order # com o número do pedido e os dados de cobrança e entrega. No modo de teste, a solicitação vai para o sandbox da Netopia.

O cliente paga com cartão na página da Netopia e volta para a página de pedido recebido da sua loja. O retorno em si não marca o pedido como pago. O pedido só é marcado como pago depois que a Netopia confirma pela IPN. Até lá, a página de pedido recebido 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. Se o pagamento foi cancelado, mostra The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time.

Se o cartão for recusado, o pedido é marcado como falho e o cliente pode pagá-lo novamente pela página do pedido. Se o plugin não estiver configurado corretamente, a página de pagamento mostra Netopia gateway is not configured properly. Please contact the store administrator.

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 aceita pagamentos com cartão somente pelo protocolo de cartão Netopia v1. Não há reembolsos nem capturas pelo WooCommerce, nem cartões salvos ou pagamentos com um clique, nem assinaturas, parcelamentos, SMS, transferências bancárias ou pagamentos em criptomoedas, e não há suporte à Netopia API v2.

Pedidos e reembolsos

Status do pedido

Pending payment: o cliente foi enviado para a Netopia, ou a Netopia ainda não enviou a IPN.

Processing or Completed: a Netopia confirmou o pagamento. O status segue Order status after payment. A nota do pedido mostra o valor, o número do cartão mascarado e a transação da Netopia; pagamentos de sandbox são marcados como [sandbox]. O ID da transação é o da transação Netopia.

On hold: o pagamento é uma pré-autorização aguardando captura no painel da Netopia, ou está em análise na Netopia. O pedido é marcado como pago quando a Netopia confirma. Um pedido também fica em espera quando o valor ou a moeda da fatura diferem do pedido, quando só parte do pagamento foi capturada, ou quando a Netopia confirma o pagamento de um pedido cancelado. A nota do pedido explica o motivo. Verifique a transação no painel da Netopia e conclua ou reembolse o pedido manualmente.

Failed: a Netopia informou um erro, por exemplo um cartão recusado. O cliente pode pagar novamente.

Cancelled: a Netopia cancelou o pagamento, ou o cliente clicou em Cancel order antes de ir para a Netopia.

Notificações atrasadas nunca rebaixam um pedido pago. Se a Netopia confirmar outro pagamento de um pedido que já está pago, uma nota pede que você reembolse o duplicado no painel da Netopia.

Reembolsos

Os reembolsos não são feitos pelo WooCommerce: o protocolo de cartão Netopia v1 não tem uma chamada de reembolso, por isso não existe o botão Refund via. Reembolse a transação no painel da Netopia. A Netopia então envia uma IPN de crédito, e o plugin registra o reembolso no pedido automaticamente, com o motivo Refund initiated by Netopia. Reembolsos parciais mantêm o status do pedido; quando não há mais nada a reembolsar, o WooCommerce marca o pedido como 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. O estoque não é reposto automaticamente.

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 > Netopia Payments. 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 na vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere-a na sua conta vibefox.net.

Sem uma chave ativa, a Netopia não é mostrada 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. Gerentes da loja conectados 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. 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 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

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 da loja ou do pedido é RON, EUR, USD ou GBP. A página de configurações mostra um aviso quando algo está faltando.

O pagamento foi feito, mas o pedido continua em Pending payment: 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 modo de manutenção, autenticação básica ou firewall bloqueando). Ative Debug log e procure as linhas de IPN em WooCommerce > Status > Logs, origem wcp_netopia_gateway. O retorno do cliente, sozinho, nunca marca o pedido como pago.

Log shows failed decrypting data: a chave privada não corresponde ao certificado do ambiente que a Netopia usou. A IPN é descriptografada com a chave do ambiente ativo e, para pagamentos iniciados antes da troca do modo de teste, com a chave do outro ambiente. A Netopia tenta novamente.

Log shows signature mismatch: a Account signature é diferente do ponto de venda que enviou a IPN. Copie-a novamente do painel da Netopia.

Log shows unknown payment request: a IPN não responde a uma solicitação de pagamento que a sua loja fez para aquele pedido naquele ambiente (sandbox ou produção). Nada é alterado.

Log shows gateway not configured: a chave privada ou a assinatura da conta está ausente. A Netopia tenta a IPN novamente, e o pagamento é registrado assim que as configurações estiverem completas.

Error on save about the certificate or private key: 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.

Order is On hold after payment: leia a nota do pedido. O pagamento pode ser uma pré-autorização ou estar em análise, o valor ou a moeda podem ter sido diferentes, só parte foi capturada, o pedido havia sido cancelado, ou um pagamento de sandbox foi confirmado enquanto a loja estava no modo de produção (nenhum dinheiro real foi recebido). Verifique a transação no painel da Netopia.

A refund made in Netopia does not appear on the order: a IPN de crédito não chegou à loja ou foi rejeitada. Verifique o log. Se necessário, crie um reembolso manual no WooCommerce.

The license block shows an error: 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 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 de licença deste plugin são sempre removidos. As configurações do gateway, incluindo as chaves salvas, e os logs só são removidos se Delete data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Netopia Payments e mobilPay são marcas registradas de seus respectivos proprietários. Este plugin não é afiliado nem endossado pela Netopia Payments.