Django Commerce

A lightweight and extensible commerce foundation for Django projects.

django-commerce provides reusable commerce primitives such as products, carts, orders, transactions, and pluggable offsite payment gateways — designed to integrate cleanly with modular Django architectures and plugin-based systems.

This package is built on top of django-plugin-system.

CAUTION: The package has been changed signifactly and README does not guide well right now. Will be modified in near future.

Features

• Base product abstraction
• Shopping cart system
• Order management
• Transaction tracking
• Extensible offsite payment gateway architecture
• Plugin-based payment providers
• Designed for reusable Django applications

Installation

Install using pip:

pip install django-commerce

Add applications to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...

    'django_plugin_system',

    'django_commerce.product',
    'django_commerce.cart',
    'django_commerce.order',
    'django_commerce.transaction',
    'django_commerce.offsite_payment_gateway',
]

Run migrations:

python manage.py migrate

Package Structure

django_commerce/
├── product/
├── cart/
├── order/
├── transaction/
└── offsite_payment_gateway/

Base Product

The package provides a reusable BaseProduct model abstraction that can be extended in your own project.

Example:

from django.db import models
from django_commerce.product.models import BaseProduct


class Product(BaseProduct):
    description = models.TextField()

Offsite Payment Gateway

The package includes an abstract offsite payment gateway system that allows developers to integrate external payment providers such as:

• Zarinpal
• Stripe Checkout
• PayPal
• Mollie
• Any redirect-based payment provider

To create a custom gateway, extend AbstractOffsitePaymentGateway.

Creating a Payment Gateway

Example:

from django.http import HttpRequest

from django_commerce.offsite_payment_gateway.models import (
    AbstractOffsitePaymentGateway
)


class ZarinpalGateway(AbstractOffsitePaymentGateway):
    name = 'zarinpal'
    _gateway_base_url = 'https://sandbox.zarinpal.com'

    def get_payment_gateway(self, order):
        transaction = self.create_transaction(order)

        callback = self.callback_url(transaction)

        return f'{self._gateway_base_url}/start/{transaction.id}?callback={callback}'

    def verify_payment(self, transaction, callback_request: HttpRequest) -> bool:
        authority = callback_request.GET.get('Authority')

        if not authority:
            return False

        # Verify payment using provider API
        # ...

        transaction.is_verified = True
        transaction.save()

        return True

Registering Gateway Plugins

Gateways are designed to work with the plugin system.

Example registration:

from django_plugin_system import register_plugin

from .gateway import ZarinpalGateway


register_plugin(
    manager='django_commerce.offsite_payment_gateway',
    title='Zarinpal Gateway',
    plugin=ZarinpalGateway,
)

Payment Callback View

The package provides a callback endpoint handler for payment verification.

Example URL configuration:

from django.urls import path

from django_commerce.offsite_payment_gateway.views import callback_view


urlpatterns = [
    path(
        'payment-callback/<int:transaction_id>',
        callback_view,
        name='payment_callback'
    ),
]

After the payment provider redirects the user back to your application, the callback view:

1. Loads the related transaction
2. Resolves the payment gateway plugin
3. Calls verify_payment
4. Verifies and finalizes the transaction

Transactions

Each payment attempt creates a Transaction object associated with:

• Order
• Payment plugin
• Verification state

This makes payment tracking and auditing easier across multiple providers.

Design Goals

This package focuses on:

• Reusability
• Extensibility
• Minimal assumptions
• Plugin-oriented architecture
• Separation of concerns

It is intended to act as a commerce foundation rather than a complete e-commerce platform.

Development

Clone the repository:

git clone <repository-url>

Install in editable mode:

pip install -e .

Run migrations from the development project:

python manage.py migrate

License

MIT License