Manual de Instalação e Configuração

Plugin WooCommerce Nhonga Payment Gateway

Versão 1.0.0

---

Índice

1. Introdução
2. Requisitos do Sistema
3. Instalação
4. Configuração Inicial
5. Configurações Avançadas
6. Testes
7. Solução de Problemas
8. Suporte

---

Introdução

O Plugin WooCommerce Nhonga Payment Gateway permite que sua loja WooCommerce aceite pagamentos através dos métodos mais populares em Moçambique: M-Pesa, e-Mola e cartões de crédito/débito.

Características Principais

• Integração Completa: Comunicação direta com a API Nhonga.net
• Múltiplos Métodos: Suporte para M-Pesa, e-Mola e cartões
• Dois Modos de Pagamento: Redirect e pagamento direto
• Segurança: Comunicação criptografada e validação de webhooks
• Logs Detalhados: Sistema completo de logging para debug
• Interface Intuitiva: Configuração simples e interface amigável

---

Requisitos do Sistema

Requisitos Mínimos

• WordPress: 5.0 ou superior
• WooCommerce: 5.0 ou superior
• PHP: 7.4 ou superior
• MySQL: 5.6 ou superior
• HTTPS: Certificado SSL válido (obrigatório)
• cURL: Extensão PHP habilitada
• JSON: Extensão PHP habilitada

Requisitos Recomendados

• WordPress: 6.0 ou superior
• WooCommerce: 7.0 ou superior
• PHP: 8.0 ou superior
• MySQL: 8.0 ou superior
• Memória PHP: 256MB ou superior
• Tempo de Execução: 60 segundos ou superior

Conta Nhonga

• Conta ativa em nhonga.net
• Chave da API válida
• Chave secreta configurada
• Webhook URL configurado

---

Instalação

Método 1: Upload Manual

1. Baixar o Plugin

   • Faça download do arquivo woocommerce-nhonga-payment.zip

2. Acessar o WordPress Admin

   • Faça login no painel administrativo do WordPress
   • Navegue para Plugins > Adicionar Novo

3. Upload do Plugin

   • Clique em "Enviar Plugin"
   • Selecione o arquivo ZIP baixado
   • Clique em "Instalar Agora"

4. Ativar o Plugin

   • Após a instalação, clique em "Ativar Plugin"

Método 2: FTP

1. Extrair Arquivos

   • Extraia o conteúdo do ZIP em seu computador

2. Upload via FTP

   • Conecte-se ao seu servidor via FTP
   • Navegue para /wp-content/plugins/
   • Faça upload da pasta woocommerce-nhonga-payment

3. Ativar no WordPress

   • Acesse Plugins > Plugins Instalados
   • Encontre "WooCommerce Nhonga Payment Gateway"
   • Clique em "Ativar"

Verificação da Instalação

Após a ativação, você deve ver:

• Mensagem de sucesso na ativação
• Nova opção em WooCommerce > Configurações > Pagamentos
• Link "Configurações" na lista de plugins

---

Configuração Inicial

Passo 1: Obter Credenciais da API

1. Acessar Nhonga.net

   • Visite nhonga.net
   • Faça login em sua conta

2. Navegar para API

   • Acesse o Dashboard
   • Clique na aba "API"

3. Copiar Credenciais

   • Copie sua "Chave da API"
   • Copie sua "Chave Secreta"

Passo 2: Configurar o Plugin

1. Acessar Configurações

   • No WordPress Admin, vá para WooCommerce > Configurações
   • Clique na aba "Pagamentos"
   • Encontre "Nhonga" e clique em "Configurar"

2. Configurações Básicas

   Ativar/Desativar: ✓ Ativar Nhonga Payment Gateway
   Título: Pagamento Nhonga
   Descrição: Pague com M-Pesa, e-Mola ou cartão de forma segura
   

3. Credenciais da API

   Chave da API: [Cole sua chave aqui]
   Chave Secreta: [Cole sua chave secreta aqui]
   Ambiente: Teste (para testes) ou Produção (para uso real)
   

4. Configurações de Pagamento

   Modo de Pagamento: Redirecionar para Nhonga (Recomendado)
   Métodos Permitidos: M-Pesa, e-Mola, Cartões
   

Passo 3: Testar Conexão

1. Teste Automático

   • Na seção "Testar Conexão", clique em "Testar Conexão"
   • Aguarde o resultado
   • Deve aparecer "✓ Conexão estabelecida com sucesso"

2. Resolver Problemas

   • Se aparecer erro, verifique suas credenciais
   • Confirme se o ambiente está correto
   • Verifique sua conexão com internet

Passo 4: Configurar Webhook

1. Obter URL do Webhook

   • A URL será: https://seusite.com/wc-api/wc_nhonga_webhook
   • Substitua "seusite.com" pelo seu domínio

2. Configurar no Nhonga.net

   • Acesse sua conta Nhonga
   • Vá para configurações de API
   • Adicione a URL do webhook
   • Salve as configurações

---

Configurações Avançadas

Modos de Pagamento

Modo Redirect (Recomendado)

• Cliente é redirecionado para página segura da Nhonga
• Maior segurança
• Suporte completo a todos os métodos
• Menor complexidade de implementação

Modo Direto

• Cliente insere dados diretamente na loja
• Experiência mais integrada
• Requer validação adicional
• Apenas para M-Pesa e e-Mola

Modo Ambos

• Cliente pode escolher o método preferido
• Máxima flexibilidade
• Requer configuração cuidadosa

Configurações de Segurança

HTTPS Obrigatório

Certificado SSL: Obrigatório
Validação: Automática
Redirecionamento: HTTP → HTTPS

Validação de Webhook

Chave Secreta: Verificação automática
IP Whitelist: Opcional (recomendado)
Timeout: 30 segundos

Configurações de Performance

Cache

Cache de Configurações: Ativado
TTL: 1 hora
Invalidação: Automática

Logs

Nível de Log: Info (produção) / Debug (desenvolvimento)
Rotação: 30 dias
Tamanho Máximo: 10MB por arquivo

---

Testes

Ambiente de Teste

1. Configurar Ambiente Dev

   Ambiente: Teste (Sandbox)
   Chave da API: Chave de teste
   Chave Secreta: Chave secreta de teste
   

2. Realizar Transação de Teste

   • Adicione um produto ao carrinho
   • Prossiga para o checkout
   • Selecione "Pagamento Nhonga"
   • Complete o pagamento de teste

3. Verificar Logs

   • Acesse WooCommerce > Status > Logs
   • Procure por logs "nhonga-payment"
   • Verifique se não há erros

Testes de Produção

1. Configurar Ambiente Prod

   Ambiente: Produção (Live)
   Chave da API: Chave de produção
   Chave Secreta: Chave secreta de produção
   

2. Teste com Valor Baixo

   • Faça um pedido de valor baixo (ex: 10 MZN)
   • Complete o pagamento real
   • Verifique se o status do pedido é atualizado

3. Verificar Webhook

   • Confirme se o webhook foi recebido
   • Verifique os logs de webhook
   • Teste cancelamento de pagamento

---

Solução de Problemas

Problemas Comuns

Erro: "Credenciais inválidas"

Causa: Chave da API ou chave secreta incorretas Solução:

1. Verifique as credenciais no painel Nhonga
2. Copie e cole novamente no plugin
3. Teste a conexão

Erro: "Webhook não recebido"

Causa: URL do webhook incorreta ou bloqueada Solução:

1. Verifique a URL: https://seusite.com/wc-api/wc_nhonga_webhook
2. Teste se a URL está acessível
3. Verifique firewall e plugins de segurança

Erro: "Pagamento não confirmado"

Causa: Problema na comunicação ou timeout Solução:

1. Verifique logs de erro
2. Confirme status na conta Nhonga
3. Atualize status do pedido manualmente se necessário

Logs de Debug

Ativar Logs

WooCommerce > Configurações > Pagamentos > Nhonga
Debug: ✓ Ativar logging

Localizar Logs

WooCommerce > Status > Logs
Arquivo: nhonga-payment-YYYY-MM-DD-hash.log

Interpretar Logs

[INFO] - Informações gerais
[ERROR] - Erros que precisam atenção
[DEBUG] - Detalhes técnicos (apenas em modo debug)

Contato para Suporte

Suporte Técnico

• Email: suporte@nhonga.net
• Horário: Segunda a Sexta, 8h às 18h
• Idioma: Português

Documentação Online

• URL: https://nhonga.net/api-docs
• Atualizações: Verificar regularmente
• FAQ: Perguntas frequentes disponíveis

---

Atualizações

Verificar Atualizações

• Acesse Plugins > Plugins Instalados
• Procure por notificações de atualização
• Sempre faça backup antes de atualizar

Changelog

• Verifique o arquivo readme.txt para mudanças
• Leia notas de versão antes de atualizar
• Teste em ambiente de desenvolvimento primeiro

---

Este manual foi gerado automaticamente para a versão 1.0.0 do plugin WooCommerce Nhonga Payment Gateway.