Metadata-Version: 2.4
Name: django-hesabpay
Version: 0.1.0
Summary: Beginner-friendly Django SDK for the HesabPay payment gateway
Author: Cyber0x3a
License: MIT
Project-URL: Homepage, https://github.com/Cyber0x3a/django-hesabpay
Project-URL: Documentation, https://docs.hesab.com/
Project-URL: Changelog, https://github.com/Cyber0x3a/django-hesabpay/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Cyber0x3a/django-hesabpay/issues
Keywords: django,hesabpay,payments,afghanistan,afn
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: httpx>=0.27
Requires-Dist: cryptography>=42
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-django>=4.8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# django-hesabpay

Beginner-friendly Django SDK for the [HesabPay Payment Gateway](https://docs.hesab.com/).

**Mental model:** `hesabpay.checkout(...)` → `@on_payment_success` for your business logic → optional status poll. Redirects are UX; webhooks are truth.

## Install

```bash
pip install django-hesabpay
```

Requires **Python 3.10+** and **Django 4.2+**.

From this repo during development:

```bash
pip install -e ".[dev]"
```

Release process: see [`RELEASING.md`](RELEASING.md). Changes: [`CHANGELOG.md`](CHANGELOG.md).

## 5-minute quickstart

### 1. Settings

```python
# settings.py
INSTALLED_APPS = [
    # ...
    "hesabpay",
]

HESABPAY = {
    "ENVIRONMENT": "sandbox",  # or "production"
    "SANDBOX_API_KEY": "your-sandbox-key",
    # "PRODUCTION_API_KEY": "your-live-key",  # when ENVIRONMENT=production
    "HANDLERS": ["shop.payments"],  # modules that register @on_payment_success
}
```

### 2. Migrate

```bash
python manage.py migrate
```

Webhook and status routes register automatically (default webhook: `/hesabpay/webhook/`).  
Copy that URL into the HesabPay dashboard.

### 3. Start checkout

```python
import hesabpay
from django.shortcuts import redirect

def pay(request, order):
    checkout = hesabpay.checkout(order, user=request.user)
    return redirect(checkout.url)
```

Or from a template:

```django
{% load hesabpay %}
{% hesabpay_checkout_button order user=request.user %}
```

JSON APIs can return `checkout.as_dict()` → `payment_id`, `checkout_url`, `status`.

### 4. Fulfill after payment

```python
# shop/payments.py
from hesabpay import on_payment_success

@on_payment_success
def fulfill(context):
    # enroll, unlock, email, ship — your product decides
    order = context.instance
    user = context.user
    if not context.is_first_success:
        return
    ...
```

Amounts are **AFN**. Currency conversion is out of scope for v1.

## Example shop

A runnable course shop lives in [`examples/basic_shop/`](examples/basic_shop/):

```bash
cd examples/basic_shop
pip install -e ../..
python manage.py migrate
python manage.py seed_courses
python manage.py createsuperuser
python manage.py runserver
```

## Multi-vendor (advanced)

After a payment succeeds, settle vendors with an encrypted PIN (documented HesabPay API):

```python
from hesabpay import transfer_to_vendors

transfer_to_vendors(
    payment=payment,
    vendors=[{"account_number": "700000001", "amount": 50}],
    pin="1234",
)
```

Auto-settle is off by default (`AUTO_VENDOR_TRANSFER`).

## Commands

```bash
python manage.py hesabpay doctor
python manage.py hesabpay simulate-webhook <payment_reference>
```

In Django admin: payments, webhook events, vendor payouts, activity logs.  
Use **Replay fulfillment handlers** on webhook events if a handler failed after payment was already acked.

## Docs for contributors / AI agents

See [`AGENTS.md`](AGENTS.md) for architecture, guardrails, and progress.

Official HesabPay docs: https://docs.hesab.com/
