django-repaykit 0.1.0

Reusable Django financing, repayment schedule, statement, and settlement workflow app powered by repaykit.

django-repaykit

Reusable Django financing, repayment schedule, statement, and settlement workflow app powered by repaykit.

repaykit is the pure Python calculation engine. django-repaykit is the reusable Django app that owns financing accounts, repayments, settlement requests, default UI, admin, permissions, selectors, exports, and service adapters. Host projects own origination workflows, approvals, tenancy, payment gateways, compliance rules, accounting, notifications, and external integrations.

The package is service-first: views, forms, admin actions, APIs, batch imports, payment gateways, and workflows should call services instead of putting business logic in forms or templates.

Installation

pip install django-repaykit

Add the app:

INSTALLED_APPS = [
    # ...
    "django_repaykit",
]

Add URLs:

from django.urls import include, path

urlpatterns = [
    path("financing/", include("django_repaykit.urls")),
]

Run migrations:

python manage.py migrate

Optional demo data:

python manage.py repaykit_seed_demo

Service-First Creation

from datetime import date
from decimal import Decimal

from django_repaykit.services import FinancingAccountService

account = FinancingAccountService().create_financing(
    user=user,
    borrower_name="Ali Bin Abu",
    principal=Decimal("10000.00"),
    annual_rate=Decimal("0.08"),
    term_value=24,
    term_unit="months",
    payment_frequency="monthly",
    repayment_method="flat_rate",
    start_date=date.today(),
    source="ao_workflow",
    external_reference="APP-000123",
)

Recording Repayment From An External System

from datetime import date
from decimal import Decimal

from django_repaykit.services import RepaymentService

RepaymentService().record_repayment(
    account=account,
    amount=Decimal("500.00"),
    paid_at=date.today(),
    source="billplz",
    external_reference="BILL-123",
    status="confirmed",
)

Gateway signature verification, idempotency policy, and webhook security belong in the host project. Once verified, call RepaymentService.

Generating Statement

from datetime import date

from django_repaykit.services import StatementService

statement = StatementService().get_statement(account, as_of=date.today())

Only confirmed repayments affect statements. Pending, failed, reversed, and cancelled repayments remain visible as repayment records but are ignored by repaykit ledger calculations.

Settlement Quote

from datetime import date

from django_repaykit.services import SettlementService

quote = SettlementService().quote_full_settlement(account=account, as_of=date.today())

Settlement payments are recorded with RepaymentService(source="settlement"); the package does not implement payment gateway settlement collection.

Template Override

DJANGO_REPAYKIT = {
    "BASE_TEMPLATE": "base.html",
}

You can also override any package template by placing a matching file under templates/django_repaykit/ in the host project.

Permission Override

DJANGO_REPAYKIT = {
    "PERMISSION_CLASS": "myapp.permissions.MyPermission",
}

The default policy is secure:

• staff can manage all accounts
• account owners can view their schedule and statement
• account owners can request settlement
• repayment recording is staff-only
• anonymous users are denied

Service Override

DJANGO_REPAYKIT = {
    "REPAYMENT_SERVICE_CLASS": "myapp.services.MyRepaymentService",
}

Supported service settings:

• FINANCING_ACCOUNT_SERVICE_CLASS
• REPAYMENT_SERVICE_CLASS
• STATEMENT_SERVICE_CLASS
• SETTLEMENT_SERVICE_CLASS

Default Settings

DJANGO_REPAYKIT = {
    "BASE_TEMPLATE": "django_repaykit/base.html",
    "LOGIN_REQUIRED": True,
    "DEFAULT_CURRENCY": "MYR",
    "DEFAULT_REPAYMENT_METHOD": "flat_rate",
    "DEFAULT_PAYMENT_FREQUENCY": "monthly",
    "PERMISSION_CLASS": "django_repaykit.permissions.DefaultRepayKitPermission",
    "FINANCING_ACCOUNT_SERVICE_CLASS": "django_repaykit.services.FinancingAccountService",
    "REPAYMENT_SERVICE_CLASS": "django_repaykit.services.RepaymentService",
    "STATEMENT_SERVICE_CLASS": "django_repaykit.services.StatementService",
    "SETTLEMENT_SERVICE_CLASS": "django_repaykit.services.SettlementService",
    "ENABLE_SETTLEMENT_REQUESTS": True,
    "ENABLE_REPAYMENT_RECORDING": True,
}

Security Notes

Public URLs use UUIDs and never expose integer primary keys. UUID URLs are not authorization: views still enforce permissions through selectors and the permission class. Host projects must validate business rules, compliance rules, product policies, and payment gateway signatures.

Disclaimer

django-repaykit is a software integration package for repayment and financing calculations. It does not provide legal, accounting, Shariah, lending, tax, regulatory, or financial advice. Users are responsible for validating all policies and calculations for their own products, jurisdictions, and compliance requirements.