django-hesabpay

Beginner-friendly Django SDK for the HesabPay Payment Gateway.

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

pip install django-hesabpay

Requires Python 3.10+ and Django 4.2+.

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
    # Public HTTPS origin for redirects (tunnel or production domain):
    "PUBLIC_BASE_URL": "https://your-domain.example",
    "SUCCESS_URL": "/success/",
    "FAILURE_URL": "/failure/",
    "HANDLERS": ["shop.payments"],  # modules that register @on_payment_success
}

PUBLIC_BASE_URL turns relative SUCCESS_URL / FAILURE_URL paths into absolute HTTPS URLs HesabPay can redirect to. You can also set SITE_URL as an alias for PUBLIC_BASE_URL.

2. Migrate

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

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() with payment_id, checkout_url, status, and items.

4. Fulfill after payment

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

When AUTO_VENDOR_TRANSFER is False (the default), nothing is sent automatically. After a verified success webhook you call the helper yourself with any vendor list — the SDK batches to 13 vendors per API request (HesabPay allows up to 16):

from hesabpay import on_payment_success, transfer_to_vendors

@on_payment_success
def settle(context):
    if not context.is_first_success:
        return
    transfer_to_vendors(
        payment=context.payment,
        vendors=[
            {"account_number": "700000001", "amount": 50},
            {"account_number": "700000002", "amount": 15},
            # ... 40 more accounts — sent as multiple batches of 13
        ],
    )

Optional decorator style (with AUTO_VENDOR_TRANSFER: True + MERCHANT_PIN):

from hesabpay import vendor_resolver

@vendor_resolver
def vendors_for(context):
    return [{"account_number": "700000001", "amount": 50}]

transfer_to_vendors(...) merges duplicate account numbers, splits into batches of 13, and returns a list of payout records (one per batch).

Commands

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/