Documentação da API

Integre facilmente soluções de pagamento com a API da Nhonga.net

Sumário

Introdução

Bem-vindo à documentação da API da Nhonga.net! Esta documentação fornece informações sobre como integrar o sistema de pagamentos da Nhonga.net em sua aplicação.

URL Base da API

Todas as requisições devem ser feitas para:

https://nhonga.net/api

Visão Geral

A API da Nhonga.net permite que você integre pagamentos em sua aplicação com suporte para vários métodos de pagamento, incluindo M-Pesa, e-Mola e cartões de crédito/débito.

Integração Simples

Endpoints RESTful fáceis de implementar

Segurança

Autenticação via chave API e SSL

Processamento Rápido

Transações processadas em segundos

Autenticação

Todas as requisições à API devem incluir um cabeçalho de autenticação contendo sua chave API. 

curl --location 'https://nhonga.net/api/payment/create' \
--header 'apiKey: SUA_CHAVE_API' \
--header 'Content-Type: application/json' \
--data '{ ... }'

Obtendo sua Chave API

Para obter sua chave API:

  1. Faça login na sua conta Nhonga.net
  2. Acesse a seção Dashboard
  3. Navegue até a aba API
  4. Gere ou copie sua chave API

Importante

Mantenha sua chave API em segredo. Não a compartilhe publicamente ou em repositórios de código.

Criar Pagamento

Crie uma transação de pagamento para redirecionar o cliente ao checkout da Nhonga.net.

POST /payment/create

Parâmetros de Requisição

Parâmetro Tipo Obrigatório Descrição
amount Number Sim Valor total da transação
context String Sim Descrição/contexto do pagamento
callbackUrl String Sim URL para receber notificação de conclusão
returnUrl String Sim URL para redirecionar após pagamento
currency String Não Moeda (padrão: MZN)
enviroment String Não Ambiente (dev|prod, padrão: prod)

Exemplo de Requisição

{
  "amount": 1500,
  "context": "Pagamento do curso de programação",
  "callbackUrl": "https://seusite.com/webhook",
  "returnUrl": "https://seusite.com/obrigado",
  "currency": "MZN",
  "enviroment": "prod"
}

Exemplo de Resposta

{
  "success": true,
  "error": null,
  "redirectUrl": "https://nhonga.net/checkout/abc123",
  "id": "txn_123456789"
}

Verificar Status do Pagamento

Verifique o status de uma transação de pagamento usando seu ID.

POST /payment/status

Parâmetros de Requisição

Parâmetro Tipo Obrigatório Descrição
id String Sim ID da transação

Exemplo de Requisição

{
  "id": "txn_123456789"
}

Exemplo de Resposta

{
  "success": true,
  "status": "completed",
  "amount": 1500,
  "tax": 75,
  "method": "mpesa",
  "currency": "MZN"
}

Possíveis Status

pending

Pagamento iniciado, aguardando confirmação

completed

Pagamento confirmado e concluído

cancelled

Pagamento cancelado ou expirado

Pagamento Direto (Mobile)

Realize pagamentos diretamente via M-Pesa ou e-Mola sem redirecionar o cliente.

POST /payment/mobile

Parâmetros de Requisição

Parâmetro Tipo Obrigatório Descrição
method String Sim "mpesa" ou "emola"
amount Number Sim Valor total da transação
context String Sim Descrição/contexto do pagamento
useremail String Sim Email do usuário que está pagando
userwhatsApp String Sim WhatsApp do usuário que está pagando
phone String Sim Número Mpesa/Emola que sera feita a cobrança.

Exemplo de Requisição

{
  "method": "mpesa",
  "amount": 2500,
  "context": "Recarga de saldo",
  "useremail": "cliente@exemplo.com",
  "userwhatsApp": "841234567",
  "phone":"841416077"
}

Exemplo de Resposta

{
  "success": true,
  "error": null,
  "id": "txn_987654321",
  "currency": "MZN"
}

Webhooks

Receba notificações instantâneas quando pagamentos forem confirmados.

Notificação Instantânea

O webhook é acionado imediatamente após a confirmação do pagamento.

Cabeçalhos de Segurança

Para evitar phishing, todas as requisições de webhook incluem um cabeçalho de autenticação: 

secretKey: SUA_CHAVE_SECRETA

Corpo da Requisição

{
  "id": "txn_123456789",
  "productId": "prod_abc123",
  "method": "mpesa",
  "paid": 1500,
  "received": 1425,
  "fee": 75,
  "context": "Pagamento do curso de programação"
}

Obtendo sua Chave Secreta

Sua chave secreta pode ser encontrada na mesma seção do dashboard onde você encontrou sua chave API.

Valide sempre a autenticidade

Sempre verifique o cabeçalho secretKey antes de processar uma notificação de webhook.

Suporte

Precisa de ajuda com a integração? Nossa equipe está pronta para ajudar.

Email

Para suporte técnico ou dúvidas sobre a API:

suporte@nhonga.net

Documentação Online

Acesse nossa documentação completa online:

https://nhonga.net/api-docs

Perguntas Frequentes

Como obtenho minhas chaves de API?

Acesse sua conta no Nhonga.net, vá para o Dashboard e navegue até a seção API. Lá você encontrará suas chaves de API e segredo.

Existe um ambiente de sandbox para testes?

Sim, você pode usar o parâmetro "enviroment": "dev" para realizar transações de teste que não geram cobranças reais.

Quais métodos de pagamento são suportados?

Atualmente suportamos M-Pesa, e-Mola e cartões de crédito/débito (Visa, Mastercard).