544 lines
18 KiB
Markdown
544 lines
18 KiB
Markdown
# django-nepali-payment
|
||
|
||
Accept payments in Nepal from your Django app with a single, consistent API.
|
||
|
||
We handle **Khalti**, **eSewa**, **Fonepay** (Dynamic QR, Static QR, status
|
||
verification, tax refund) and **ConnectIPS**, so you don't have to learn four
|
||
different HTTP APIs, four different signing schemes, and four different
|
||
callback formats. You get one `PaymentManager`, one `PaymentResult`, done.
|
||
|
||
The library is deliberately lightweight. No WebSockets, no async event loops,
|
||
no background daemons. Just plain HTTPS requests through a pooled
|
||
`requests.Session`, which is why it runs happily even on shared hosting.
|
||
|
||
```bash
|
||
pip install django-nepali-payment
|
||
# or with uv
|
||
uv add django-nepali-payment
|
||
```
|
||
|
||
**Requirements:** Python 3.11+, Django 4.2+ (the library itself is not tied to a
|
||
specific Django major). It bundles `requests` for transport and `cryptography`
|
||
for ConnectIPS RSA signing.
|
||
|
||
### Contents
|
||
|
||
- [What you get](#what-you-get)
|
||
- [How it's built](#how-its-built)
|
||
- [Quick start](#quick-start) · [Tune the HTTP client](#tuning-the-http-client)
|
||
- [Initiate a payment](#initiate-a-payment) — eSewa, Khalti, Fonepay
|
||
- [Fonepay Static QR](#fonepay-static-qr)
|
||
- [ConnectIPS](#connectips)
|
||
- [Verify a payment](#verify-a-payment)
|
||
- [Errors](#errors) · [Handling callbacks safely](#handling-callbacks-safely)
|
||
- [Fonepay QR status monitoring](#fonepay-qr-status-monitoring)
|
||
- [Why polling](#why-polling-instead-of-websockets)
|
||
- [See it in action](#see-it-in-action) · [Development](#development) · [CI](#ci)
|
||
|
||
---
|
||
|
||
## What you get
|
||
|
||
- **One shape for every gateway.** Every call returns a `PaymentResult`, so
|
||
reading a success, a failure, or some provider data looks the same whether it
|
||
came from Khalti or Fonepay.
|
||
- **Signatures that just work.** We reproduced the exact signing from each
|
||
provider's reference implementation, so you don't have to debug hex vs base64
|
||
yourself:
|
||
- eSewa: HMAC-SHA256 (base64)
|
||
- Fonepay: HMAC-SHA512 (lowercase hex)
|
||
- Khalti: `Authorization: key <secret>` header
|
||
- ConnectIPS: SHA256withRSA over your merchant certificate
|
||
- **One flag for sandbox vs production.** Flip `PaymentMode` and you're done.
|
||
- **Shared-hosting-safe Fonepay monitoring.** Settlement is checked with a
|
||
lightweight polling thread rather than a WebSocket, so it works where long
|
||
connections are forbidden.
|
||
- **Fonepay extras built in.** Tax refunds and Static QR out of the box.
|
||
- **Connection reuse.** One `requests.Session` is shared across calls, with
|
||
sensible timeouts.
|
||
- **Optional retries.** `ApiService` can retry transient failures (connection
|
||
drops and HTTP 429/5xx) with exponential backoff — opt in per client.
|
||
|
||
---
|
||
|
||
## How it's built
|
||
|
||
The library has three small layers, all of which you can use directly:
|
||
|
||
- **`PaymentManager`** — the entry point. Pick a gateway, mode and secret key
|
||
once, then call `initiate_payment` / `verify_payment` (plus Fonepay tax refund
|
||
and static QR) without thinking about which provider you chose.
|
||
- **Gateway services** — one per provider (Khalti, eSewa, Fonepay, ConnectIPS).
|
||
Every service extends `BasePaymentService`, which stores the things all
|
||
gateways share (the HTTP client, the sandbox-vs-production base URL, and a
|
||
"turn any error into a failed result" helper). Each service only implements
|
||
its own initiate/verify logic and signing.
|
||
- **Request/response models** — `PaymentResult` is the universal answer type.
|
||
Each gateway also has typed request models. The request models use Python
|
||
`dataclass(slots=True)` and serialize themselves with `dataclasses.asdict`,
|
||
so they are small in memory and safe to pass straight to a provider.
|
||
|
||
Under the hood everything is synchronous HTTPS through a pooled
|
||
`requests.Session` — no event loops, WebSockets or daemons.
|
||
|
||
---
|
||
|
||
## Quick start
|
||
|
||
Create a manager once for your gateway and mode, then reuse it:
|
||
|
||
```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 the same `PaymentResult`, with these attributes:
|
||
|
||
| Field | What it holds |
|
||
| ------------ | ------------------------------------------------ |
|
||
| `success` | Did the operation succeed? |
|
||
| `message` | Human-readable message (no secrets are logged) |
|
||
| `data` | Gateway-specific response object (may be `None`) |
|
||
| `status` | Reserved; currently unused (always `200`) |
|
||
| `error_code` | Reserved; currently unused (always `None`) |
|
||
|
||
`PaymentResult` also behaves like a `bool` inside an `if`, and exposes
|
||
`raise_for_status()` to turn a failure into a raised `PaymentError` when you'd
|
||
rather not handle it inline:
|
||
|
||
```python
|
||
result = manager.initiate_payment(PaymentResult, request).raise_for_status()
|
||
print(result.data) # only reached if the payment actually started
|
||
```
|
||
|
||
### Tuning the HTTP client
|
||
|
||
By default the manager creates its own `ApiService` — a pooled
|
||
`requests.Session` with a 15s timeout. You can inject your own to change the
|
||
timeout, enable retries, or share one session across several managers:
|
||
|
||
```python
|
||
from nepali_payment import PaymentManager, PaymentMethod, PaymentMode
|
||
from nepali_payment.http import ApiService
|
||
|
||
api = ApiService(
|
||
timeout=30.0, # default request timeout (seconds)
|
||
retries=2, # retry transient failures 0..N times (default 0)
|
||
retry_backoff=1.0, # initial backoff seconds; doubles each attempt
|
||
)
|
||
|
||
manager = PaymentManager(
|
||
PaymentMethod.KHALTI,
|
||
PaymentMode.SANDBOX,
|
||
secret_key="your-secret-key",
|
||
api=api,
|
||
)
|
||
```
|
||
|
||
The `ApiService` is shared and reuse-cached, so many calls never open a new
|
||
connection. Call `api.close()` (or `manager._api_service().close()`) to release
|
||
pooled connections when your app shuts down.
|
||
|
||
> Retries are off by default because re-sending a *payment initiation* could
|
||
> double-charge. Enable them only for endpoints that are safe to repeat.
|
||
|
||
---
|
||
|
||
## Initiate a payment
|
||
|
||
Each gateway has its own request model, but the call is always
|
||
`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", # your eSewa product code
|
||
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
|
||
```
|
||
|
||
eSewa redirects the customer to a hosted payment form.
|
||
|
||
### 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, # in 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 later
|
||
```
|
||
|
||
> 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 this to the customer
|
||
```
|
||
|
||
The dynamic QR bakes the amount into the QR. Fonepay settlement happens
|
||
asynchronously, so you'll usually pair this with the [status monitor](#fonepay-qr-status-monitoring).
|
||
|
||
---
|
||
|
||
## Fonepay Static QR
|
||
|
||
A static QR is a single, fixed merchant QR (think: printed at a point of sale).
|
||
The customer types in the amount when they scan, so you don't need an amount up
|
||
front. Fetch the QR payload once per station and render it:
|
||
|
||
```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 this once for this station
|
||
```
|
||
|
||
> `process_static_qr` is Fonepay-only, just like the tax refund. Calling it on
|
||
> another gateway raises `ValidationError`. For settlement checks, use
|
||
> `verify_payment` or the `FonepayPaymentMonitor` with the payment's PRN.
|
||
|
||
---
|
||
|
||
## ConnectIPS
|
||
|
||
ConnectIPS is a **form POST** gateway. You render a hidden form and hand the
|
||
customer over to ConnectIPS, who redirects them back once the payment is done.
|
||
It signs with **SHA256withRSA** using a merchant certificate (a `.pfx`, `.p12`
|
||
or `.pem` key), so instead of a secret key the manager 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, # switch to PRODUCTION when ready
|
||
secret_key="", # unused for ConnectIPS
|
||
config=config,
|
||
)
|
||
```
|
||
|
||
Initiate the payment. You get back the hidden form fields to render, plus the
|
||
URL to POST them to:
|
||
|
||
```python
|
||
from nepali_payment.models.connectips import PaymentRequest
|
||
|
||
request = PaymentRequest(
|
||
order_id="order-123",
|
||
amount=12500, # NPR amount
|
||
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 # the ConnectIPS login form URL
|
||
```
|
||
|
||
When ConnectIPS redirects back to your callback, verify using the query
|
||
parameters it sent (plus the amount you expected):
|
||
|
||
```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
|
||
```
|
||
|
||
> ConnectIPS needs the `cryptography` package, which is installed automatically
|
||
> with the library. The certificate is loaded inside the service and never
|
||
> logged.
|
||
|
||
---
|
||
|
||
## Verify a payment
|
||
|
||
The verification call is also the same across gateways — only the argument
|
||
differs:
|
||
|
||
```python
|
||
# Khalti: pass the pidx
|
||
result = manager.verify_payment(PaymentResult, pidx)
|
||
|
||
# Fonepay: pass a 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: pass the base64 response echoed back from the payment form
|
||
result = manager.verify_payment(PaymentResult, base64_response)
|
||
```
|
||
|
||
---
|
||
|
||
## Errors
|
||
|
||
There are two kinds of failures, and the library keeps them separate:
|
||
|
||
**1. Gateway failures return a failed `PaymentResult`** — no exception is
|
||
raised, so you can treat rejections, non-2xx responses and network hiccups as
|
||
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
|
||
```
|
||
|
||
If you'd rather stop and handle it with a raised error, 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 one exception to "failures don't raise": it raises `PaymentError`
|
||
> instead of returning a failed result, matching how eSewa's own API reports
|
||
> errors. Catch it (or catch `PaymentError`) when working with eSewa directly.
|
||
|
||
**2. Developer-facing mistakes raise typed exceptions.** An empty secret, an
|
||
unsupported gateway, a `None`/empty/invalid request — these are bugs in your
|
||
call, so they fail loudly:
|
||
|
||
```python
|
||
from nepali_payment.exceptions import (
|
||
PaymentError, ValidationError, AuthenticationError,
|
||
NetworkError, ProviderError, UnsupportedGatewayError,
|
||
)
|
||
```
|
||
|
||
The rule of thumb: if a real payment could fail and you should check `success`,
|
||
it comes back as a `PaymentResult`; if it's a mistake in your code, it raises.
|
||
|
||
---
|
||
|
||
## Handling callbacks safely
|
||
|
||
When Khalti, eSewa or ConnectIPS redirects the customer back to your site, you
|
||
verify the payment before marking it complete. A few practical rules:
|
||
|
||
- **Verify server-side, don't trust the query string.** The `pidx` (Khalti) or
|
||
`data` (eSewa) in the URL is only an identifier — always round-trip it through
|
||
`manager.verify_payment`, never assume it means "paid". For ConnectIPS, pass
|
||
the callback parameters *and* the amount you expected.
|
||
- **Reconcile the amount.** Confirm the verified amount matches your order's
|
||
amount before marking it paid. Khalti and eSewa report the paid amount in
|
||
`result.data.total_amount`, ConnectIPS in `result.data.txn_amount`. The
|
||
`examples/` app does exactly this — a settled payment for the wrong amount is
|
||
stored as `failed`, never `paid`.
|
||
- **Keep the callback handler idempotent.** A provider may redeliver a callback,
|
||
or a user may refresh. Guard your handler so re-verifying the same order is a
|
||
no-op rather than a duplicate charge or state flip.
|
||
- **Check the order belongs to your user.** If callbacks are unauthenticated
|
||
(`@csrf_exempt`), binding the order to the current request/session still
|
||
matters in real apps before you release goods.
|
||
|
||
---
|
||
|
||
## Fonepay QR status monitoring
|
||
|
||
Fonepay's QR flow is asynchronous. The customer scans, pays, and you need to
|
||
find out _when_ it settles. Here it's plain **HTTP polling** so it works on shared hosting.
|
||
|
||
Attach a few handlers and start a poller per payment:
|
||
|
||
```python
|
||
from datetime import timedelta
|
||
from nepali_payment import FonepayPaymentMonitor, PaymentCredentials
|
||
|
||
monitor = FonepayPaymentMonitor( # defaults shown; tweak as you like
|
||
timeout=timedelta(minutes=15), # overall session lifetime
|
||
interval=timedelta(seconds=5), # delay between polls
|
||
)
|
||
|
||
@monitor.on("status") # fires on every poll
|
||
def on_status(args):
|
||
print("status:", args.prn, args.payment_status)
|
||
|
||
@monitor.on("verified") # payment settled
|
||
def on_verified(args):
|
||
print("verified:", args.prn, args.success)
|
||
monitor.stop(args.prn) # done with this one
|
||
|
||
@monitor.on("timeout") # no terminal state in time
|
||
def on_timeout(args):
|
||
print("timeout:", args.prn)
|
||
|
||
@monitor.on("error") # poller/network 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,
|
||
),
|
||
)
|
||
```
|
||
|
||
You can also manage sessions directly:
|
||
|
||
```python
|
||
monitor.is_monitoring("order-123") # is a poller active?
|
||
monitor.stop("order-123") # stop one poller
|
||
monitor.dispose() # stop all and release the session
|
||
```
|
||
|
||
> **In Django, don't `sleep()` in the request path.** Start the monitor in a
|
||
> background task (Celery), a management command, or your task runner so the
|
||
> HTTP response returns immediately.
|
||
|
||
---
|
||
|
||
## Why polling instead of WebSockets?
|
||
|
||
Shared hosting usually forbids persistent connections, daemon processes and
|
||
async event loops. The polling monitor needs none of those. It just issues
|
||
plain HTTPS requests on a background thread through the shared
|
||
`requests.Session`. The result is a library that's dependency-light,
|
||
synchronous, and deploys cleanly on shared hosting and typical Django setups
|
||
alike.
|
||
|
||
---
|
||
|
||
## See it in action
|
||
|
||
There's a complete, runnable Django project in [`examples/`](examples/). It
|
||
wires every gateway into real views, an `Order` model, provider callbacks and a
|
||
Fonepay background monitor — the way you'd actually use the library for real:
|
||
|
||
```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 Fonepay settlements in a worker
|
||
```
|
||
|
||
See [`examples/README.md`](examples/README.md) for the full walkthrough. It
|
||
defaults to sandbox mode and reads credentials from environment variables, so
|
||
you can poke around the UI and the request/response shapes safely before going
|
||
live.
|
||
|
||
---
|
||
|
||
## Development
|
||
|
||
We use [uv](https://docs.astral.sh/uv/) for the environment and tooling:
|
||
|
||
```bash
|
||
# install the package and dev deps in a venv
|
||
uv sync --extra dev
|
||
|
||
# lint (library, tests and the example app)
|
||
uv run ruff check nepali_payment tests examples/payments
|
||
|
||
# format
|
||
uv run ruff format --check nepali_payment tests examples/payments
|
||
|
||
# run all tests (live sandbox tests are skipped without credentials)
|
||
uv run pytest
|
||
|
||
# run tests with a coverage report (the suite sits around 97%)
|
||
uv run pytest --cov=nepali_payment
|
||
|
||
# live sandbox smoke tests (hits real provider endpoints)
|
||
NEPALI_PAYMENT_ESEWA_SECRET=... \
|
||
NEPALI_PAYMENT_KHALTI_SECRET=... \
|
||
NEPALI_PAYMENT_FONEPAY_SECRET=... NEPALI_PAYMENT_FONEPAY_MERCHANT=... \
|
||
NEPALI_PAYMENT_FONEPAY_USERNAME=... NEPALI_PAYMENT_FONEPAY_PASSWORD=... \
|
||
uv run pytest tests/test_live_api.py -v
|
||
```
|
||
|
||
## CI
|
||
|
||
GitHub Actions workflows live in `.github/workflows/`:
|
||
|
||
- **`ci.yml`** lints, formats, and runs a Python × Django test matrix with an
|
||
80% coverage gate, plus a package build check, on every push/PR.
|
||
- **`live-api.yml`** runs real sandbox smoke tests, either manually or on a
|
||
schedule; skipped unless provider credentials are configured as repo secrets.
|
||
- **`release.yml`** builds and publishes to PyPI on `django-nepali-payment/v*`
|
||
tags.
|