Metadata-Version: 2.4
Name: django-hesabpay
Version: 0.1.3
Summary: Beginner-friendly Django SDK for the HesabPay payment gateway
Author: Cyber0x3a
License-Expression: MIT
Project-URL: Documentation, https://docs.hesab.com/
Project-URL: Homepage, https://pypi.org/project/django-hesabpay/
Keywords: django,hesabpay,payments,afghanistan,afn
Classifier: Development Status :: 4 - Beta
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: 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/).

Start a hosted checkout with `hesabpay.checkout(...)`, then run your business logic in `@on_payment_success`. Redirects are for UX. Verified webhooks are the source of truth.

## Install

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

Requires Python 3.10+ and Django 4.2+.

## 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. The default webhook path is `/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()` with `payment_id`, `checkout_url`, `status`, and `items`.

### 4. Fulfill after payment

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

@on_payment_success
def fulfill(context):
    # Your product decides: enroll, unlock, email, ship, etc.
    order = context.instance
    user = context.user
    items = context.items          # local HesabPayPaymentItem rows
    webhook_items = context.webhook_items  # items list from HesabPay webhook
    if not context.is_first_success:
        return
    ...
```

HesabPay webhooks include an `items` array (same shape as create-session). The SDK stores those line items locally and exposes them on the payment context and status endpoint.

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

## 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>
```

Django admin includes payments, webhook events, vendor payouts, and activity logs. Use **Replay fulfillment handlers** on a webhook event if a handler failed after the payment was already acknowledged.

## Official API docs

https://docs.hesab.com/
