Files
django-nepali-payments/README.md
T
2026-09-03 02:04:37 +05:45

462 lines
15 KiB
Markdown

# django-nepali-payment
<p align="center"><i>Nepal payments, one API. Khalti, eSewa, Fonepay, ConnectIPS.</i></p>
<p align="center">
<a href="https://github.com/S4NKALP/django-nepali-payments/actions/workflows/ci.yml">
<img src="https://github.com/S4NKALP/django-nepali-payments/actions/workflows/ci.yml/badge.svg" alt="CI">
</a>
<a href="https://pypi.org/project/django-nepali-payment/">
<img src="https://img.shields.io/pypi/v/django-nepali-payment" alt="PyPI version">
</a>
<a href="https://pypi.org/project/django-nepali-payment/">
<img src="https://img.shields.io/pypi/pyversions/django-nepali-payment" alt="Python versions">
</a>
<img src="https://img.shields.io/badge/Django-4.2%20%7C%205.0%20%7C%206.0%20%7C%206.1-092E20" alt="Django">
<a href="https://github.com/S4NKALP/django-nepali-payments/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/S4NKALP/django-nepali-payments" alt="License">
</a>
<a href="https://github.com/S4NKALP/django-nepali-payments">
<img src="https://img.shields.io/github/last-commit/S4NKALP/django-nepali-payments" alt="Last commit">
</a>
</p>
Accept Nepal payments from Django with **one consistent API** for Khalti, eSewa,
Fonepay (Dynamic QR, Static QR, status, tax refund) and ConnectIPS. No four
HTTP APIs, no four signing schemes, no four callback formats. One
`PaymentManager`, one `PaymentResult`.
Lightweight: plain HTTPS through a pooled `requests.Session`. No WebSockets, no
async loops, no daemons, and runs on shared hosting.
```bash
pip install django-nepali-payment
# or with uv
uv add django-nepali-payment
```
**Requirements:** Python 3.11+, Django 4.2+, `requests`, `cryptography`
(for ConnectIPS signing).
## Highlights
<p align="center"><i>Why you'll love it.</i></p>
- **One shape for every gateway**: every call returns a `PaymentResult`.
- **Signatures that just work**: reproduced from each provider's reference:
- eSewa: HMAC-SHA256 (base64)
- Fonepay: HMAC-SHA512 (lowercase hex)
- Khalti: `Authorization: key <secret>` header
- ConnectIPS: SHA256withRSA over your merchant certificate
- **Sandbox ↔ production in one flag**: flip `PaymentMode`.
- **Shared-hosting-safe polling**: Fonepay settlement checked with a lightweight
polling thread, not a WebSocket.
- **Fonepay extras built in**: tax refunds and Static QR.
- **Connection reuse**: one shared `requests.Session`, sensible timeouts.
- **Optional retries**: exponential backoff on transient failures; opt in.
## Architecture
<p align="center"><i>Simple by design. Three layers, total.</i></p>
Three small layers, all usable directly:
- **`PaymentManager`**: the entry point. Pick gateway, mode, secret once; call
`initiate_payment` / `verify_payment` (plus Fonepay refund / static QR).
- **Gateway services**: one per provider, extending `BasePaymentService`
(shared HTTP client, sandbox/prod URL, error handling). Each implements only
its own initiate/verify logic and signing.
- **Models**: `PaymentResult` is the universal answer type; per-gateway typed
requests are `dataclass(slots=True)` and self-serialize.
## Quick start
<p align="center"><i>Your first payment in seconds.</i></p>
```python
from nepali_payment import PaymentManager, PaymentMethod, PaymentMode, PaymentResult
manager = PaymentManager(
payment_method=PaymentMethod.ESEWA, # or KHALTI, FONEPAY
payment_mode=PaymentMode.SANDBOX, # switch to PRODUCTION when ready
secret_key="your-secret-key",
)
```
Every call returns a `PaymentResult`:
| Field | What it holds |
| ------------ | ------------------------------------------------ |
| `success` | Did the operation succeed? |
| `message` | Human-readable message (no secrets logged) |
| `data` | Gateway-specific response object (may be `None`) |
| `status` | Reserved; unused (always `200`) |
| `error_code` | Reserved; unused (always `None`) |
It's truthy like a `bool`, and exposes `raise_for_status()` to raise on failure:
```python
result = manager.initiate_payment(PaymentResult, request).raise_for_status()
print(result.data) # only reached if the payment actually started
```
### Custom HTTP client
```python
from nepali_payment.http import ApiService
api = ApiService(
timeout=30.0, # seconds; default 15
retries=2, # retry transient failures (default 0)
retry_backoff=1.0, # initial backoff; doubles each attempt
)
manager = PaymentManager(
PaymentMethod.KHALTI, PaymentMode.SANDBOX,
secret_key="your-secret-key",
api=api,
)
```
Call `api.close()` (or `manager._api_service().close()`) to release pooled
connections on shutdown.
> Retries default **off**: re-sending a payment initiation could double-charge.
> Enable only for endpoints safe to repeat.
## Initiate a payment
<p align="center"><i>Same call, every gateway.</i></p>
```python
manager.initiate_payment(PaymentResult, request)
```
### eSewa
```python
from nepali_payment.models.esewa import PaymentRequest as EsewaRequest
request = EsewaRequest(
amount="100",
total_amount="113", # amount + tax + charges
transaction_uuid="order-123",
product_code="EPAYTEST",
signed_field_names="total_amount,transaction_uuid,product_code",
)
result = manager.initiate_payment(PaymentResult, request)
if result.success:
redirect_url = result.data.payment_url # send the customer here
```
### Khalti
```python
from nepali_payment.models.khalti import PaymentRequest as KhaltiRequest
request = KhaltiRequest(
return_url="https://yoursite.com/callback",
website_url="https://yoursite.com",
amount=1000, # paisa (NPR 10.00)
purchase_order_id="order-123",
purchase_order_name="My Order",
)
result = manager.initiate_payment(PaymentResult, request)
if result.success:
redirect_url = result.data.payment_url # send the customer here
pidx = result.data.pidx # keep for verification
```
> Khalti amounts are in **paisa** (1 NPR = 100 paisa).
### Fonepay (Dynamic QR)
```python
from nepali_payment.models.fonepay import QrRequest
request = QrRequest(
amount="100", remarks1="Order 123", remarks2="Main",
prn="order-123", merchant_code="NBQM",
username="merchant-user", password="merchant-password",
)
result = manager.initiate_payment(PaymentResult, request)
if result.success:
qr_data = result.data.qr_message # show to the customer
```
The dynamic QR bakes the amount in; settlement is async, so pair it with the
[status monitor](#fonepay-qr-status-monitoring).
## Fonepay Static QR
<p align="center"><i>Set it once, scan forever.</i></p>
One fixed merchant QR; the customer types the amount at scan. Fetch once per
station:
```python
from nepali_payment.models.fonepay import StaticQrRequest
request = StaticQrRequest(
prn="merchant-station", merchant_code="NBQM",
username="merchant-user", password="merchant-password",
)
result = manager.process_static_qr(PaymentResult, request)
if result.success:
static_qr = result.data.qr_message # render/print once for this station
```
> `process_static_qr` is Fonepay-only (like the tax refund). On other gateways
> it raises `ValidationError`. For settlement, use `verify_payment` or the
> `FonepayPaymentMonitor` with the payment's PRN.
## ConnectIPS
<p align="center"><i>Bank-grade signing, dead-simple form.</i></p>
A **form POST** gateway signed with **SHA256withRSA** using a merchant
certificate (`.pfx`, `.p12` or `.pem`). Instead of a secret key it takes a
config object:
```python
import os
from nepali_payment.enums import PaymentMethod, PaymentMode
from nepali_payment.services.connectips import ConnectIpsConfig
config = ConnectIpsConfig(
merchant_id="YOUR_MERCHANT_ID",
app_id="YOUR_APP_ID",
app_name="Demo App",
app_password="Your App Password",
cert_path=os.environ["CONNECTIPS_CERT_PATH"], # .pfx / .p12 / .pem
cert_password=os.environ.get("CONNECTIPS_CERT_PASSWORD", ""),
success_url="https://yoursite.com/payments/success",
failure_url="https://yoursite.com/payments/failure",
)
manager = PaymentManager(
payment_method=PaymentMethod.CONNECTIPS,
payment_mode=PaymentMode.SANDBOX,
secret_key="", # unused for ConnectIPS
config=config,
)
```
Initiate to get the hidden form fields:
```python
from nepali_payment.models.connectips import PaymentRequest
request = PaymentRequest(
order_id="order-123",
amount=12500, # NPR
description="Order 123",
)
result = manager.initiate_payment(PaymentResult, request)
if result.success:
form = result.data.form_fields # hidden inputs to render
action = result.data.target_url # ConnectIPS login form URL
```
Verify on the callback with the query params plus the expected amount:
```python
import json
callback = {
"TXNID": "order-123",
"STATUS": "SUCCESS", # optional; FAILED/CANCELLED short-circuits
"expectedAmount": 12500,
}
result = manager.verify_payment(PaymentResult, json.dumps(callback))
if result.success:
trans_ref_id = result.data.trans_ref_id
```
> `cryptography` installs automatically. The cert is loaded inside the service
> and never logged.
## Verify a payment
<p align="center"><i>One call to confirm it's real.</i></p>
Same call everywhere, only the argument differs:
```python
# Khalti: pass the pidx
result = manager.verify_payment(PaymentResult, pidx)
# Fonepay: JSON string with prn + merchant credentials
import json
payload = json.dumps({
"prn": "order-123",
"merchantCode": "NBQM",
"username": "merchant-user",
"password": "merchant-password",
})
result = manager.verify_payment(PaymentResult, payload)
# eSewa: base64 response echoed back from the payment form
result = manager.verify_payment(PaymentResult, base64_response)
```
## Errors
<p align="center"><i>Failures are data. Bugs are loud.</i></p>
Two kinds, kept separate:
**1. Gateway failures return a failed `PaymentResult`**: no exception, so
rejections, non-2xx responses and network hiccups are data:
```python
result = manager.initiate_payment(PaymentResult, request)
if result.success:
... # proceed with checkout
else:
logger.warning("Payment failed: %s", result.message) # no secrets logged
```
Prefer raising? Chain `raise_for_status()`:
```python
result = manager.initiate_payment(PaymentResult, request).raise_for_status()
# this line only runs if the payment actually started
```
> **eSewa is the exception:** it raises `PaymentError` instead of returning a
> failed result, matching eSewa's own API. Catch it when working with eSewa.
**2. Developer mistakes raise typed exceptions.** An empty secret, an
unsupported gateway, a `None`/empty/invalid request, these fail loudly:
```python
from nepali_payment.exceptions import (
PaymentError, ValidationError, AuthenticationError,
NetworkError, ProviderError, UnsupportedGatewayError,
)
```
Rule of thumb: if a real payment could fail and you should check `success`, it
comes back as a `PaymentResult`; if it's a bug in your call, it raises.
## Handling callbacks safely
<p align="center"><i>Never trust the query string. Always verify.</i></p>
- **Verify server-side, don't trust the query string.** The `pidx` (Khalti) or
`data` (eSewa) is only an identifier; always round-trip through
`manager.verify_payment`. For ConnectIPS, pass the params _and_ the expected
amount.
- **Reconcile the amount** against your order before marking paid: Khalti/eSewa
report it in `result.data.total_amount`, ConnectIPS in
`result.data.txn_amount`. The `examples/` app stores a wrong-amount settlement
as `failed`, never `paid`.
- **Keep the handler idempotent.** Providers may redeliver; a user may refresh.
Re-verifying the same order should be a no-op.
- **Check the order belongs to your user.** If callbacks are `@csrf_exempt`,
still bind the order to the request/session before releasing goods.
## Fonepay QR status monitoring
<p align="center"><i>Know the moment it settles.</i></p>
Settlement is async, so poll for it with plain **HTTP polling**, shared-hosting
safe:
```python
from datetime import timedelta
from nepali_payment import FonepayPaymentMonitor, PaymentCredentials
monitor = FonepayPaymentMonitor(
timeout=timedelta(minutes=15), # overall session lifetime
interval=timedelta(seconds=5), # delay between polls
)
@monitor.on("status") # every poll
def on_status(args):
print("status:", args.prn, args.payment_status)
@monitor.on("verified") # settled
def on_verified(args):
print("verified:", args.prn, args.success)
monitor.stop(args.prn)
@monitor.on("timeout")
def on_timeout(args):
print("timeout:", args.prn)
@monitor.on("error")
def on_error(args):
print("error:", args.prn, args.error_message)
monitor.start("order-123", PaymentCredentials(
secret_key="...", merchant_code="NBQM",
username="u", password="p", sandbox_mode=True,
))
```
Session management:
```python
monitor.is_monitoring("order-123") # is a poller active?
monitor.stop("order-123") # stop one
monitor.dispose() # stop all, release session
```
> **In Django, don't `sleep()` in the request path.** Start the monitor in a
> background task (Celery), a management command, or a task runner so the HTTP
> response returns immediately.
### Why polling, not WebSockets?
<i>Shared hosting said no. We said fine.</i>
Shared hosting forbids persistent connections, daemons and async loops. The
monitoring thread needs none of these; it is plain HTTPS on the shared
`requests.Session`. Dependency-light, synchronous, deploys cleanly.
## See it in action
<p align="center"><i>Wired up, ready to run.</i></p>
A runnable Django app in [`examples/`](examples/) wires every gateway into real
views, an `Order` model, provider callbacks and a Fonepay background monitor:
```bash
cd examples
uv sync
cp .env.sample .env
uv run python manage.py makemigrations payments
uv run python manage.py migrate
uv run python manage.py runserver # open http://127.0.0.1:8000/
uv run python manage.py monitor_fonepay # poll settlements in a worker
```
Defaults to sandbox; credentials come from env vars. See
[`examples/README.md`](examples/README.md) for the full walkthrough.
## Development
<p align="center"><i>One command to get going.</i></p>
Tooling via [uv](https://docs.astral.sh/uv/):
```bash
uv sync --extra dev # venv + dev deps
uv run ruff check nepali_payment tests examples/payments # lint
uv run ruff format --check nepali_payment tests examples/payments
uv run pytest # tests (~97% coverage with --cov)
NEPALI_PAYMENT_ESEWA_SECRET=... ... uv run pytest tests/test_live_api.py -v
```
## Contributing
<p align="center"><i>PRs welcome, big or small.</i></p>
Contributions are welcome. Open an issue or submit a PR.
1. Fork the repo
2. Create a feature branch (`git checkout -b my-branch`)
3. Make your changes
4. Submit a pull request