Metadata-Version: 2.4
Name: lxcor-billa
Version: 0.1.2
Summary: Credit-based billing for Django APIs — pluggable payment backends (Stripe, PayPal, stub), credit pack catalogue, and per-key balance tracking.
Author-email: Alexandre Scozzafave Alves <frontdesk@lxcor.com>
License: MIT
Project-URL: Homepage, https://github.com/lxcor/api-suite/tree/main/billa
Project-URL: Repository, https://github.com/lxcor/api-suite
Keywords: django,billing,stripe,paypal,credits,api
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=3.2
Requires-Dist: djangorestframework>=3.14
Requires-Dist: lxcor-reggi>=0.1.0
Requires-Dist: lxcor-kotta>=0.1.0
Provides-Extra: stripe
Requires-Dist: stripe>=5.0; extra == "stripe"
Provides-Extra: paypal
Requires-Dist: paypalrestsdk>=1.13; extra == "paypal"
Dynamic: license-file

# billa

Credit-based billing for Django APIs.

`billa` provides a pluggable payment backend (Stripe, PayPal, or a local stub for development), a credit pack catalogue, per-key balance tracking, and a `BillerThrottle` that enforces credit limits on API requests.

Part of the [lxcor/api-suite](https://github.com/lxcor/api-suite).

## Install

```bash
pip install lxcor-billa           # core + stub backend
pip install lxcor-billa[stripe]   # include Stripe
pip install lxcor-billa[paypal]   # include PayPal
```

## Setup

```python
# settings.py
INSTALLED_APPS = [
    ...
    'reggi',  # required
    'kotta',  # required
    'billa',
]

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'kotta.throttle.AnonEndpointThrottle',
        'kotta.throttle.TierThrottle',
        'billa.throttle.BillerThrottle',
    ],
}
```

```python
# urls.py
urlpatterns = [
    path('', include('billa.urls')),
]
```

## Settings

| Setting | Default | Description |
|---|---|---|
| `BILLA_PAYMENT_BACKEND` | `'billa.backends.stub.StubPaymentBackend'` | Active payment backend |
| `BILLA_MERCHANT_NAME` | `''` | Merchant name shown on terms and pricing pages |
| `BILLA_CONTACT_EMAIL` | `''` | Contact email shown on terms page |
| `BILLA_CURRENCY` | `'USD'` | Currency code for all transactions |
| `BILLA_SUCCESS_URL` | `''` | Redirect URL after successful checkout |
| `BILLA_CANCEL_URL` | `''` | Redirect URL after cancelled checkout |
| `BILLA_UPGRADE_URL` | `''` | URL appended to 402 responses when credits are exhausted |
| `BILLA_STRIPE_MODE` | `'test'` | `'test'` or `'live'` |
| `BILLA_PAYPAL_MODE` | `'sandbox'` | `'sandbox'` or `'live'` |

## Navbar and footer fragments

```django
{% include "billa/_navbar_links.html" %}   {# Pricing link #}
{% include "billa/_footer_links.html" %}   {# Terms link #}
```

## Management commands

| Command | Description |
|---|---|
| `dumppacks` | Export credit pack catalogue to JSON |
| `loadpacks` | Import credit pack catalogue from JSON |

## License

MIT
