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)

Easiest path — register a resolver (no dotted settings path needed):

from hesabpay import vendor_resolver, on_payment_success

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

Then either:

1. Set AUTO_VENDOR_TRANSFER: True and MERCHANT_PIN in HESABPAY, or
2. Call it yourself:

from hesabpay import transfer_to_vendors_from_context

@on_payment_success
def settle(context):
    if context.is_first_success:
        transfer_to_vendors_from_context(context)

You can still pass an explicit list to transfer_to_vendors(...) when you want full control. VENDOR_RESOLVER settings paths still work as a fallback.

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/