dj-stripe

2.10.3 · active · verified Wed Apr 15

dj-stripe seamlessly integrates Stripe payments with Django applications, providing a robust, database-backed representation of Stripe models. It handles webhooks, subscriptions, and customer management out-of-the-box. The current version is 2.10.3, and it maintains an active development pace with frequent minor and major releases.

Warnings

breaking Upgrading to dj-stripe 2.10.x requires first upgrading to 2.9.x due to a migration reset. Additionally, many database fields have been removed from models and replaced by `stripe_data` property accessors, requiring code changes.
Fix: Ensure you are on a 2.9.x release before upgrading to 2.10.x. Review your code for direct model field access and update to use `model_instance.stripe_data['field_name']` where applicable.
breaking Deprecated settings (`DJSTRIPE_WEBHOOK_TOLERANCE`, `DJSTRIPE_WEBHOOK_SECRET`), the `Order` model, `Customer.add_card` method, and direct support for `Source` and `SourceTransaction` models have been removed. The `Source` models are now under `djstripe.models.payment_methods` and are slated for full removal.
Fix: Remove deprecated settings from `settings.py`. Update code relying on removed models or methods. Reconfigure webhooks via the Django admin interface instead of `DJSTRIPE_WEBHOOK_SECRET`.
breaking Direct upgrade paths for older dj-stripe versions are restricted. For instance, upgrading to 2.8.0 is not possible from versions older than 2.5.0, and upgrading to 2.7.0 is not possible from versions older than 2.4.0.
Fix: Consult release notes for your current and target versions. Perform staged upgrades (e.g., old -> 2.4.0 -> 2.7.0 -> 2.9.0 -> 2.10.x) if jumping multiple major versions.
gotcha dj-stripe has a strict `requires_python` range. Starting with 2.8.0, Python 3.7 is no longer supported. The latest versions (2.10.x) require Python >=3.11 and support newer Django versions like 4.1 and 4.2.
Fix: Verify your Python and Django versions against the `dj-stripe` version you plan to use. Upgrade your Python environment and Django project if necessary.
gotcha Webhook endpoint configuration has changed significantly. Starting from 2.7.0, webhook endpoints are primarily configured via the Django administration interface, replacing older methods like `DJSTRIPE_WEBHOOK_SECRET` (which was removed in 2.9.0).
Fix: Migrate webhook secret configuration from `settings.py` to the Django admin panel under the dj-stripe app. Ensure your Stripe dashboard is configured to send events to the `/djstripe/webhook/` endpoint.

Install

pip install dj-stripe Install latest version

Imports

Customer
```
from djstripe.models import Customer
```

Subscription

from djstripe.models import Subscription

WebhookMessage

from djstripe.models import WebhookMessage

Source
wrong:
```
from djstripe.models import Source
```
correct:
```
from djstripe.models.payment_methods import Source
```
The Source and SourceTransaction models were moved in 2.9.0 and are pending removal in future versions.

Quickstart

To get started with dj-stripe, add it to your `INSTALLED_APPS`, configure your Stripe API keys (test and live) in `settings.py`, and include dj-stripe's URLs in your project's `urls.py`. Remember to run `python manage.py migrate` after installation to create the necessary database tables. For webhooks, configure them via the Django admin (since 2.7.0).

import os

# settings.py
INSTALLED_APPS = [
    # ... other apps
    'djstripe',
    # ...
]

STRIPE_LIVE_MODE = False  # Set to True for production
STRIPE_TEST_SECRET_KEY = os.environ.get('STRIPE_TEST_SECRET_KEY', 'sk_test_YOUR_TEST_SECRET_KEY')
STRIPE_LIVE_SECRET_KEY = os.environ.get('STRIPE_LIVE_SECRET_KEY', 'sk_live_YOUR_LIVE_SECRET_KEY')

STRIPE_TEST_PUBLIC_KEY = os.environ.get('STRIPE_TEST_PUBLIC_KEY', 'pk_test_YOUR_TEST_PUBLIC_KEY')
STRIPE_LIVE_PUBLIC_KEY = os.environ.get('STRIPE_LIVE_PUBLIC_KEY', 'pk_live_YOUR_LIVE_PUBLIC_KEY')

# urls.py
from django.urls import path, include

urlpatterns = [
    # ... other paths
    path('djstripe/', include('djstripe.urls', namespace="djstripe")),
    # ...
]

# Run migrations
# python manage.py migrate

view raw JSON →