Metadata-Version: 2.4
Name: django-repaykit
Version: 0.1.0
Summary: Reusable Django financing, repayment schedule, statement, and settlement workflow app powered by repaykit.
Project-URL: Homepage, https://github.com/finsure-techlab/django-repaykit
Project-URL: Issues, https://github.com/finsure-techlab/django-repaykit/issues
Author: django-repaykit contributors
License-Expression: MIT
License-File: LICENSE
Keywords: django,financing,loan,repaykit,repayment,schedule,settlement
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: django>=5.2
Requires-Dist: repaykit>=1.0.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-django; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# django-repaykit

Reusable Django financing, repayment schedule, statement, and settlement workflow app powered by
[`repaykit`](https://pypi.org/project/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

```bash
pip install django-repaykit
```

Add the app:

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

Add URLs:

```python
from django.urls import include, path

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

Run migrations:

```bash
python manage.py migrate
```

Optional demo data:

```bash
python manage.py repaykit_seed_demo
```

## Service-First Creation

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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.

