# Nhonga API - Python Library
Biblioteca Python para integração com a API de pagamentos da Nhonga.net.
## Instalação
```bash
pip install nhonga-api
```
## Configuração
```python
from nhonga_api import NhongaAPI
nhonga = NhongaAPI({
"api_key": "SUA_CHAVE_API",
"secret_key": "SUA_CHAVE_SECRETA", # Opcional, necessária para webhooks
"base_url": "https://nhonga.net/api/" # Opcional, padrão já configurado
})
```
## Uso
### Criar Pagamento
```python
from nhonga_api import NhongaAPI, NhongaError, Currency, Environment
try:
payment = nhonga.create_payment({
"amount": 1500,
"context": "Pagamento do curso de programação",
"callbackUrl": "https://seusite.com/webhook",
"returnUrl": "https://seusite.com/obrigado",
"currency": Currency.MZN,
"enviroment": Environment.PRODUCTION
})
if payment["success"]:
print("URL de redirecionamento:", payment["redirectUrl"])
print("ID da transação:", payment["id"])
else:
print("Erro:", payment["error"])
except NhongaError as e:
print("Erro da API Nhonga:", e)
```
### Verificar Status do Pagamento
```python
try:
status = nhonga.get_payment_status({
"id": "txn_123456789"
})
print("Status:", status["status"])
print("Valor:", status["amount"])
print("Método:", status["method"])
print("Taxa:", status["tax"])
except NhongaError as e:
print("Erro ao verificar status:", e)
```
### Pagamento Direto Mobile
```python
from nhonga_api import PaymentMethod
try:
mobile_payment = nhonga.create_mobile_payment({
"method": PaymentMethod.MPESA,
"amount": 2500,
"context": "Recarga de saldo",
"useremail": "cliente@exemplo.com",
"userwhatsApp": "841234567",
"phone": "841416077"
})
if mobile_payment["success"]:
print("ID da transação:", mobile_payment["id"])
else:
print("Erro:", mobile_payment["error"])
except NhongaError as e:
print("Erro no pagamento mobile:", e)
```
### Processamento de Webhooks
#### Com Flask
```python
from flask import Flask, request, jsonify
from nhonga_api import NhongaAPI, NhongaError
app = Flask(__name__)
nhonga = NhongaAPI({"api_key": "SUA_CHAVE_API", "secret_key": "SUA_CHAVE_SECRETA"})
@app.route('/webhook', methods=['POST'])
def webhook():
try:
secret_key = request.headers.get('secretkey')
payload = request.get_json()
def processar_pagamento(webhook_data):
print("Pagamento confirmado:", webhook_data["id"])
print("Valor pago:", webhook_data["paid"])
print("Valor recebido:", webhook_data["received"])
print("Taxa:", webhook_data["fee"])
# Processar o pagamento confirmado
# Atualizar banco de dados, enviar email, etc.
nhonga.process_webhook(payload, secret_key, processar_pagamento)
return jsonify({"status": "success"}), 200
except NhongaError as e:
print("Webhook inválido:", e)
return jsonify({"error": "Invalid webhook"}), 400
if __name__ == '__main__':
app.run(host='0.0.0.0', port=3000)
```
#### Com FastAPI
```python
from fastapi import FastAPI, Request, HTTPException, Header
from nhonga_api import NhongaAPI, NhongaError
from typing import Optional
app = FastAPI()
nhonga = NhongaAPI({"api_key": "SUA_CHAVE_API", "secret_key": "SUA_CHAVE_SECRETA"})
@app.post("/webhook")
async def webhook(request: Request, secretkey: Optional[str] = Header(None)):
try:
if not secretkey:
raise HTTPException(status_code=400, detail="Missing secret key")
payload = await request.json()
def processar_pagamento(webhook_data):
print("Pagamento confirmado:", webhook_data["id"])
# Processar pagamento...
nhonga.process_webhook(payload, secretkey, processar_pagamento)
return {"status": "success"}
except NhongaError as e:
raise HTTPException(status_code=400, detail="Invalid webhook")
# Para executar: uvicorn main:app --host 0.0.0.0 --port 3000
```
## Tipos e Enums
A biblioteca inclui tipos e enums para melhor experiência de desenvolvimento:
```python
from nhonga_api import (
PaymentStatus,
PaymentMethod,
Currency,
Environment,
CreatePaymentRequest,
PaymentStatusResponse,
MobilePaymentRequest,
WebhookPayload
)
# Enums disponíveis
PaymentStatus.PENDING # "pending"
PaymentStatus.COMPLETED # "completed"
PaymentStatus.CANCELLED # "cancelled"
PaymentMethod.MPESA # "mpesa"
PaymentMethod.EMOLA # "emola"
Currency.MZN # "MZN"
Currency.USD # "USD"
Environment.PRODUCTION # "prod"
Environment.DEVELOPMENT # "dev"
```
## Context Manager
Use context manager para gerenciamento automático de recursos:
```python
with NhongaAPI({"api_key": "SUA_CHAVE_API"}) as nhonga:
payment = nhonga.create_payment({
"amount": 1000,
"context": "Teste de pagamento",
"enviroment": Environment.DEVELOPMENT
})
print("Pagamento criado:", payment["id"])
```
## Tratamento de Erros
A biblioteca usa a classe `NhongaError` para erros específicos da API:
```python
from nhonga_api import NhongaError
try:
payment = nhonga.create_payment(payment_data)
except NhongaError as e:
print("Erro da API Nhonga:", e.message)
print("Código de status:", e.status_code)
except Exception as e:
print("Erro inesperado:", e)
```
## Ambiente de Desenvolvimento
Para testes, use `Environment.DEVELOPMENT` nas requisições de pagamento:
```python
from nhonga_api import Environment
payment = nhonga.create_payment({
"amount": 1000,
"context": "Teste de pagamento",
"enviroment": Environment.DEVELOPMENT # Não gera cobrança real
})
```
## Exemplos Completos
Veja o arquivo `examples.py` para exemplos completos de uso com Flask, FastAPI e outras funcionalidades.
## Requisitos
- Python 3.7+
- requests >= 2.25.0
- typing-extensions >= 4.0.0
## Desenvolvimento
Para contribuir com o desenvolvimento:
```bash
# Clonar repositório
git clone https://github.com/nhonga/nhonga-python
cd nhonga-python
# Instalar dependências de desenvolvimento
pip install -e ".[dev]"
# Executar testes
pytest
# Verificar tipos
mypy nhonga_api
# Formatar código
black nhonga_api
```
## Suporte
Para suporte técnico, entre em contato:
- Email: support@nhonga.net
- Documentação: https://nhonga.net/api-docs
## Licença
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/mucamba/nhonga-api-python",
"name": "nhonga-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "nhonga payment api mozambique mpesa emola",
"author": "Nhonga API Library",
"author_email": "support@nhonga.net",
"download_url": "https://files.pythonhosted.org/packages/3d/c2/18e41e2ddb160420f5bedbf2f6675d1129431d33a5770b0e877a0c667625/nhonga_api-1.0.0.tar.gz",
"platform": null,
"description": "# Nhonga API - Python Library\n\nBiblioteca Python para integra\u00e7\u00e3o com a API de pagamentos da Nhonga.net.\n\n## Instala\u00e7\u00e3o\n\n```bash\npip install nhonga-api\n```\n\n## Configura\u00e7\u00e3o\n\n```python\nfrom nhonga_api import NhongaAPI\n\nnhonga = NhongaAPI({\n \"api_key\": \"SUA_CHAVE_API\",\n \"secret_key\": \"SUA_CHAVE_SECRETA\", # Opcional, necess\u00e1ria para webhooks\n \"base_url\": \"https://nhonga.net/api/\" # Opcional, padr\u00e3o j\u00e1 configurado\n})\n```\n\n## Uso\n\n### Criar Pagamento\n\n```python\nfrom nhonga_api import NhongaAPI, NhongaError, Currency, Environment\n\ntry:\n payment = nhonga.create_payment({\n \"amount\": 1500,\n \"context\": \"Pagamento do curso de programa\u00e7\u00e3o\",\n \"callbackUrl\": \"https://seusite.com/webhook\",\n \"returnUrl\": \"https://seusite.com/obrigado\",\n \"currency\": Currency.MZN,\n \"enviroment\": Environment.PRODUCTION\n })\n\n if payment[\"success\"]:\n print(\"URL de redirecionamento:\", payment[\"redirectUrl\"])\n print(\"ID da transa\u00e7\u00e3o:\", payment[\"id\"])\n else:\n print(\"Erro:\", payment[\"error\"])\n \nexcept NhongaError as e:\n print(\"Erro da API Nhonga:\", e)\n```\n\n### Verificar Status do Pagamento\n\n```python\ntry:\n status = nhonga.get_payment_status({\n \"id\": \"txn_123456789\"\n })\n\n print(\"Status:\", status[\"status\"])\n print(\"Valor:\", status[\"amount\"])\n print(\"M\u00e9todo:\", status[\"method\"])\n print(\"Taxa:\", status[\"tax\"])\n \nexcept NhongaError as e:\n print(\"Erro ao verificar status:\", e)\n```\n\n### Pagamento Direto Mobile\n\n```python\nfrom nhonga_api import PaymentMethod\n\ntry:\n mobile_payment = nhonga.create_mobile_payment({\n \"method\": PaymentMethod.MPESA,\n \"amount\": 2500,\n \"context\": \"Recarga de saldo\",\n \"useremail\": \"cliente@exemplo.com\",\n \"userwhatsApp\": \"841234567\",\n \"phone\": \"841416077\"\n })\n\n if mobile_payment[\"success\"]:\n print(\"ID da transa\u00e7\u00e3o:\", mobile_payment[\"id\"])\n else:\n print(\"Erro:\", mobile_payment[\"error\"])\n \nexcept NhongaError as e:\n print(\"Erro no pagamento mobile:\", e)\n```\n\n### Processamento de Webhooks\n\n#### Com Flask\n\n```python\nfrom flask import Flask, request, jsonify\nfrom nhonga_api import NhongaAPI, NhongaError\n\napp = Flask(__name__)\nnhonga = NhongaAPI({\"api_key\": \"SUA_CHAVE_API\", \"secret_key\": \"SUA_CHAVE_SECRETA\"})\n\n@app.route('/webhook', methods=['POST'])\ndef webhook():\n try:\n secret_key = request.headers.get('secretkey')\n payload = request.get_json()\n\n def processar_pagamento(webhook_data):\n print(\"Pagamento confirmado:\", webhook_data[\"id\"])\n print(\"Valor pago:\", webhook_data[\"paid\"])\n print(\"Valor recebido:\", webhook_data[\"received\"])\n print(\"Taxa:\", webhook_data[\"fee\"])\n \n # Processar o pagamento confirmado\n # Atualizar banco de dados, enviar email, etc.\n\n nhonga.process_webhook(payload, secret_key, processar_pagamento)\n return jsonify({\"status\": \"success\"}), 200\n \n except NhongaError as e:\n print(\"Webhook inv\u00e1lido:\", e)\n return jsonify({\"error\": \"Invalid webhook\"}), 400\n\nif __name__ == '__main__':\n app.run(host='0.0.0.0', port=3000)\n```\n\n#### Com FastAPI\n\n```python\nfrom fastapi import FastAPI, Request, HTTPException, Header\nfrom nhonga_api import NhongaAPI, NhongaError\nfrom typing import Optional\n\napp = FastAPI()\nnhonga = NhongaAPI({\"api_key\": \"SUA_CHAVE_API\", \"secret_key\": \"SUA_CHAVE_SECRETA\"})\n\n@app.post(\"/webhook\")\nasync def webhook(request: Request, secretkey: Optional[str] = Header(None)):\n try:\n if not secretkey:\n raise HTTPException(status_code=400, detail=\"Missing secret key\")\n \n payload = await request.json()\n\n def processar_pagamento(webhook_data):\n print(\"Pagamento confirmado:\", webhook_data[\"id\"])\n # Processar pagamento...\n\n nhonga.process_webhook(payload, secretkey, processar_pagamento)\n return {\"status\": \"success\"}\n \n except NhongaError as e:\n raise HTTPException(status_code=400, detail=\"Invalid webhook\")\n\n# Para executar: uvicorn main:app --host 0.0.0.0 --port 3000\n```\n\n## Tipos e Enums\n\nA biblioteca inclui tipos e enums para melhor experi\u00eancia de desenvolvimento:\n\n```python\nfrom nhonga_api import (\n PaymentStatus,\n PaymentMethod, \n Currency,\n Environment,\n CreatePaymentRequest,\n PaymentStatusResponse,\n MobilePaymentRequest,\n WebhookPayload\n)\n\n# Enums dispon\u00edveis\nPaymentStatus.PENDING # \"pending\"\nPaymentStatus.COMPLETED # \"completed\"\nPaymentStatus.CANCELLED # \"cancelled\"\n\nPaymentMethod.MPESA # \"mpesa\"\nPaymentMethod.EMOLA # \"emola\"\n\nCurrency.MZN # \"MZN\"\nCurrency.USD # \"USD\"\n\nEnvironment.PRODUCTION # \"prod\"\nEnvironment.DEVELOPMENT # \"dev\"\n```\n\n## Context Manager\n\nUse context manager para gerenciamento autom\u00e1tico de recursos:\n\n```python\nwith NhongaAPI({\"api_key\": \"SUA_CHAVE_API\"}) as nhonga:\n payment = nhonga.create_payment({\n \"amount\": 1000,\n \"context\": \"Teste de pagamento\",\n \"enviroment\": Environment.DEVELOPMENT\n })\n print(\"Pagamento criado:\", payment[\"id\"])\n```\n\n## Tratamento de Erros\n\nA biblioteca usa a classe `NhongaError` para erros espec\u00edficos da API:\n\n```python\nfrom nhonga_api import NhongaError\n\ntry:\n payment = nhonga.create_payment(payment_data)\nexcept NhongaError as e:\n print(\"Erro da API Nhonga:\", e.message)\n print(\"C\u00f3digo de status:\", e.status_code)\nexcept Exception as e:\n print(\"Erro inesperado:\", e)\n```\n\n## Ambiente de Desenvolvimento\n\nPara testes, use `Environment.DEVELOPMENT` nas requisi\u00e7\u00f5es de pagamento:\n\n```python\nfrom nhonga_api import Environment\n\npayment = nhonga.create_payment({\n \"amount\": 1000,\n \"context\": \"Teste de pagamento\",\n \"enviroment\": Environment.DEVELOPMENT # N\u00e3o gera cobran\u00e7a real\n})\n```\n\n## Exemplos Completos\n\nVeja o arquivo `examples.py` para exemplos completos de uso com Flask, FastAPI e outras funcionalidades.\n\n## Requisitos\n\n- Python 3.7+\n- requests >= 2.25.0\n- typing-extensions >= 4.0.0\n\n## Desenvolvimento\n\nPara contribuir com o desenvolvimento:\n\n```bash\n# Clonar reposit\u00f3rio\ngit clone https://github.com/nhonga/nhonga-python\ncd nhonga-python\n\n# Instalar depend\u00eancias de desenvolvimento\npip install -e \".[dev]\"\n\n# Executar testes\npytest\n\n# Verificar tipos\nmypy nhonga_api\n\n# Formatar c\u00f3digo\nblack nhonga_api\n```\n\n## Suporte\n\nPara suporte t\u00e9cnico, entre em contato:\n- Email: support@nhonga.net\n- Documenta\u00e7\u00e3o: https://nhonga.net/api-docs\n\n## Licen\u00e7a\n\nMIT\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Biblioteca Python para integra\u00e7\u00e3o com a API Nhonga.net",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/mucamba/nhonga-api-python"
},
"split_keywords": [
"nhonga",
"payment",
"api",
"mozambique",
"mpesa",
"emola"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4bf40b4d23c248b36be76dc309f6d11370e13127570cf6f85ad1be20185291c7",
"md5": "1e26b461cf3262fa7ca18ecac77708f6",
"sha256": "0a69dde7c34349c65549f57b3bf7b2f32afb8f906abe67766088e9feb33853cf"
},
"downloads": -1,
"filename": "nhonga_api-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e26b461cf3262fa7ca18ecac77708f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9390,
"upload_time": "2025-08-03T08:58:23",
"upload_time_iso_8601": "2025-08-03T08:58:23.207425Z",
"url": "https://files.pythonhosted.org/packages/4b/f4/0b4d23c248b36be76dc309f6d11370e13127570cf6f85ad1be20185291c7/nhonga_api-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3dc218e41e2ddb160420f5bedbf2f6675d1129431d33a5770b0e877a0c667625",
"md5": "d296b16ffb0c6d5c644e2051bffd52d5",
"sha256": "9d9067b4fcba9bc064cfcf09ab7cb7a5f56e0162459eccf9ee41a79f32cc021b"
},
"downloads": -1,
"filename": "nhonga_api-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "d296b16ffb0c6d5c644e2051bffd52d5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 9363,
"upload_time": "2025-08-03T08:58:24",
"upload_time_iso_8601": "2025-08-03T08:58:24.661401Z",
"url": "https://files.pythonhosted.org/packages/3d/c2/18e41e2ddb160420f5bedbf2f6675d1129431d33a5770b0e877a0c667625/nhonga_api-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 08:58:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mucamba",
"github_project": "nhonga-api-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"lcname": "nhonga-api"
}
JSON
