django-hesabpay

Beginner-friendly Django SDK for the HesabPay Payment Gateway.

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

Install

pip install django-hesabpay

Requires Python 3.10+ and Django 4.2+.

From this repo during development:

pip install -e ".[dev]"

Release process: see RELEASING.md. Changes: CHANGELOG.md.

5-minute quickstart

1. Settings

# 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

python manage.py migrate

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

3. Start checkout

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:

{% 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

# 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/:

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):

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

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 for architecture, guardrails, and progress.

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