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
    "HANDLERS": ["shop.payments"],  # modules that register @on_payment_success
}

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)

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>

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/