docs: update readme

This commit is contained in:
sankalp committed 2026-09-03 01:52:19 +05:45
1 parent dce589ca98
commit 2c7fb176c9
1 file changed
+28
+28
View File
@@ -42,6 +42,8 @@ pip install django-nepali-payment
## 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)
@@ -57,6 +59,8 @@ pip install django-nepali-payment
## 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
@@ -69,6 +73,8 @@ Three small layers, all usable directly:
## Quick start
<p align="center"><i>Your first payment in seconds.</i></p>
```python
from nepali_payment import PaymentManager, PaymentMethod, PaymentMode, PaymentResult
@@ -122,6 +128,8 @@ connections on shutdown.
## Initiate a payment
<p align="center"><i>Same call, every gateway.</i></p>
```python
manager.initiate_payment(PaymentResult, request)
```
@@ -183,6 +191,8 @@ The dynamic QR bakes the amount in; settlement is async, so pair it with the
## 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:
@@ -204,6 +214,8 @@ if result.success:
## 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:
@@ -267,6 +279,8 @@ if result.success:
## Verify a payment
<p align="center"><i>One call to confirm it's real.</i></p>
Same call everywhere, only the argument differs:
```python
@@ -289,6 +303,8 @@ 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
@@ -327,6 +343,8 @@ 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
@@ -342,6 +360,8 @@ comes back as a `PaymentResult`; if it's a bug in your call, it raises.
## 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:
@@ -391,12 +411,16 @@ monitor.dispose() # stop all, release session
### 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:
@@ -415,6 +439,8 @@ Defaults to sandbox; credentials come from env vars. See
## Development
<p align="center"><i>One command to get going.</i></p>
Tooling via [uv](https://docs.astral.sh/uv/):
```bash
@@ -427,6 +453,8 @@ 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