dj-stripe 2.1.0

Introduction

dj-stripe implements all of the Stripe models, for Django. Set up your webhook and start receiving model updates. You will then have a copy of all the Stripe models available in Django models, no API traffic required!

The full documentation is available here: https://dj-stripe.readthedocs.io/

Features

• Subscriptions

• Individual charges

• Stripe Sources

• Stripe v2 and v3 support

• Supports SCA regulations, Checkout Sessions, and Payment Intents

• Tested with Stripe API 2019-09-09 (see https://dj-stripe.readthedocs.io/en/latest/api_versions.html )

Requirements

• Django >= 2.1

• Python >= 3.5

• Supports Stripe exclusively. For PayPal, see dj-paypal instead.

• PostgreSQL engine (recommended): >= 9.4

• MySQL engine: MariaDB >= 10.2 or MySQL >= 5.7

Quickstart

Install dj-stripe:

pip install dj-stripe

Add djstripe to your INSTALLED_APPS:

INSTALLED_APPS =(
    ...
    "djstripe",
    ...
)

Tell Stripe about the webhook (Stripe webhook docs can be found here) using the full URL of your endpoint from the urls.py step above (e.g. https://example.com/stripe/webhook).

Add your Stripe keys and set the operating mode:

STRIPE_LIVE_PUBLIC_KEY = os.environ.get("STRIPE_LIVE_PUBLIC_KEY", "<your publishable key>")
STRIPE_LIVE_SECRET_KEY = os.environ.get("STRIPE_LIVE_SECRET_KEY", "<your secret key>")
STRIPE_TEST_PUBLIC_KEY = os.environ.get("STRIPE_TEST_PUBLIC_KEY", "<your publishable key>")
STRIPE_TEST_SECRET_KEY = os.environ.get("STRIPE_TEST_SECRET_KEY", "<your secret key>")
STRIPE_LIVE_MODE = False  # Change to True in production
DJSTRIPE_WEBHOOK_SECRET = "whsec_xxx"  # Get it from the section in the Stripe dashboard where you added the webhook endpoint

Add some payment plans via the Stripe.com dashboard.

Add to urls.py:

path("stripe/", include("djstripe.urls", namespace="djstripe")),

Run the commands:

python manage.py migrate

python manage.py djstripe_init_customers

python manage.py djstripe_sync_plans_from_stripe

Running the Tests

Assuming the tests are run against PostgreSQL:

createdb djstripe
pip install tox
tox

2.1.0 (2019-09-12)

• Dropped Django 2.0 support

• The Python stripe library minimum version is now 2.32.0, also 2.36.0 is excluded due to a regression (#991).

• Dropped previously-deprecated Charge.fee_details property.

• Dropped previously-deprecated Transfer.fee_details property.

• Dropped previously-deprecated field_name parameter to sync_from_stripe_data

• Dropped previously-deprecated alias StripeObject of StripeModel

• Dropped previously-deprecated alias PaymentMethod of DjstripePaymentMethod

• Dropped previously-deprecated properties Charge.source_type and Charge.source_stripe_id

• enums.PaymentMethodType has been deprecated, use enums.DjstripePaymentMethodType

• Made SubscriptionItem.quantity nullable as per Plans with usage_type="metered" (follow-up to #865)

• Added manage commands djstripe_sync_models and djstripe_process_events (#727, #89)

• Fixed issue with re-creating a customer after Customer.purge() (#916)

• Fixed sync of Customer Bank Accounts (#829)

• Fixed Subscription.is_status_temporarily_current() (#852)

• New models

  • Payment Intent

  • Setup Intent

  • Payment Method

  • Session

• Added fields to Customer model: address, invoice_prefix, invoice_settings, phone, preferred_locales, tax_exempt

Changes from API 2018-11-08:

• Added Invoice.auto_advance, deprecated Invoice.closed and Invoice.forgiven, see https://stripe.com/docs/billing/invoices/migrating-new-invoice-states#autoadvance

Changes from API 2019-02-19:

• Major changes to Account fields, see https://stripe.com/docs/upgrades#2019-02-19 , updated Account fields to match API 2019-02-19:

• Added Account.business_profile, .business_type, .company, .individual, .requirements, .settings

• Deprecated the existing fields, to be removed in 2.2

• Special handling of the icon and logo fields:

  • Renamed Account.business_logo to Account.branding_icon (note that in Stripe’s API Account.business_logo was renamed to Account.settings.branding_icon, and Account.business_logo_large (which we didn’t have a field for) was renamed to Account.settings.branding_logo)

  • Added deprecated property for Account.business_logo

  • Added Account.branding_logo as a ForeignKey

  • Populate Account.branding_icon and .branding_logo from the new Account.settings.branding.icon and .logo

Changes from API 2019-03-14:

• Renamed Invoice.application_fee to Invoice.application_fee_amount (added deprecated property for the old name)

• Removed Invoice.date, in place of Invoice.created (added deprecated property for the old name)

• Added Invoice.status_transitions

• Renamed Customer.account_balance to Customer.balance (added deprecated property for the old name)

• Renamed Customer.payment_methods to Customer.customer_payment_methods

• Added new SubscriptionStatus.incomplete and SubscriptionStatus.incomplete_expired statuses (#974)

• Added new BalanceTransactionType values (#983)

2.0.5 (2019-09-12)

This is a bugfix-only version:

• Avoid stripe==2.36.0 due to regression (#991)

2.0.4 (2019-09-09)

This is a bugfix-only version:

• Fixed irreversible migration (#909)

2.0.3 (2019-06-11)

This is a bugfix-only version:

• In _get_or_create_from_stripe_object, wrap create _create_from_stripe_object in transaction, fixes TransactionManagementError on race condition in webhook processing (#877/#903).

2.0.2 (2019-06-09)

This is a bugfix-only version:

• Don’t save event objects if the webhook processing fails (#832).

• Fixed IntegrityError when REMOTE_ADDR is an empty string.

• Deprecated field_name parameter to sync_from_stripe_data

2.0.1 (2019-04-29)

This is a bugfix-only version:

• Fixed an error on invoiceitem.updated (#848).

• Handle test webhook properly in recent versions of Stripe API (#779). At some point 2018 Stripe silently changed the ID used for test events and evt_00000000000000 is not used anymore.

• Fixed OperationalError seen in migration 0003 on postgres (#850).

• Fixed issue with migration 0003 not being unapplied correctly (#882).

• Fixup missing SubscriptionItem.quantity on Plans with usage_type="metered" (#865).

• Fixed Plan.create() (#870).

2.0.0 (2019-03-01)

• The Python stripe library minimum version is now 2.3.0.

• PaymentMethod has been renamed to DjstripePaymentMethod (#841). An alias remains but will be removed in the next version.

• Dropped support for Django < 2.0, Python < 3.4.

• Dropped previously-deprecated stripe_objects module.

• Dropped previously-deprecated stripe_timestamp field.

• Dropped previously-deprecated Charge.receipt_number field.

• Dropped previously-deprecated StripeSource alias for Card

• Dropped previously-deprecated SubscriptionView, CancelSubscriptionView and CancelSubscriptionForm.

• Removed the default value from DJSTRIPE_SUBSCRIPTION_REDIRECT.

• All stripe_id fields have been renamed id.

• Charge.source_type has been deprecated. Use Charge.source.type.

• Charge.source_stripe_id has been deprecated. Use Charge.source.id.

• All deprecated Transfer fields (Stripe API < 2017-04-06), have been dropped. This includes date, destination_type (type), failure_code, failure_message, statement_descriptor and status.

• Fixed IntegrityError when REMOTE_ADDR is missing (#640).

• New models: - ApplicationFee - ApplicationFeeRefund - BalanceTransaction - CountrySpec - ScheduledQuery - SubscriptionItem - TransferReversal - UsageRecord

• The fee and fee_details attributes of both the Charge and Transfer objects are no longer stored in the database. Instead, they access their respective new balance_transaction foreign key. Note that fee_details has been deprecated on both models.

• The fraudulent attribute on Charge is now a property that checks the fraud_details field.

• Object key validity is now always enforced (#503).

• Customer.sources no longer refers to a Card queryset, but to a Source queryset. In order to correctly transition, you should change all your references to customer.sources to customer.legacy_cards instead. The legacy_cards attribute already exists in 1.2.0.

• Customer.sources_v3 is now named Customer.sources.

• A new property Customer.payment_methods is now available, which allows you to iterate over all of a customer’s payment methods (sources then cards).

• Card.customer is now nullable and cards are no longer deleted when their corresponding customer is deleted (#654).

• Webhook signature verification is now available and is preferred. Set the DJSTRIPE_WEBHOOK_SECRET setting to your secret to start using it.

• StripeObject has been renamed StripeModel. An alias remains but will be removed in the next version.

• The metadata key used in the Customer object can now be configured by changing the DJSTRIPE_SUBSCRIBER_CUSTOMER_KEY setting. Setting this to None or an empty string now also disables the behaviour altogether.

• Text-type fields in dj-stripe will no longer ever be None. Instead, any falsy text field will return an empty string.

• Switched test runner to pytest-django

• StripeModel.sync_from_stripe_data() will now automatically retrieve related objects and populate foreign keys (#681)

• Added Coupon.name

• Added Transfer.balance_transaction

• Exceptions in webhooks are now re-raised as well as saved in the database (#833)

1.2.4 (2019-02-27)

This is a bugfix-only version:

• Allow billing_cycle_anchor argument when creating a subscription (#814)

• Fixup plan amount null with tier plans (#781)

• Update Cancel subscription view tests to match backport in f64af57

• Implement Invoice._manipulate_stripe_object_hook for compatability with API 2018-11-08 (#771)

• Fix product webhook for type=”good” (#724)

• Add trial_from_plan, trial_period_days args to Customer.subscribe() (#709)

1.2.3 (2018-10-13)

This is a bugfix-only version:

• Updated Subscription.cancel() for compatibility with Stripe 2018-08-23 (#723)

1.2.2 (2018-08-11)

This is a bugfix-only version:

• Fixed an error with request.urlconf in some setups (#562)

• Always save text-type fields as empty strings in db instead of null (#713)

• Fix support for DJSTRIPE_SUBSCRIBER_MODEL_MIGRATION_DEPENDENCY (#707)

• Fix reactivate() with Stripe API 2018-02-28 and above

1.2.1 (2018-07-18)

This is a bugfix-only version:

• Fixed various Python 2.7 compatibility issues

• Fixed issues with max_length of receipt_number

• Fixed various fields incorrectly marked as required

• Handle product webhook calls

• Fix compatibility with stripe-python 2.0.0

1.2.0 (2018-06-11)

The dj-stripe 1.2.0 release resets all migrations.

Do not upgrade to 1.2.0 directly from 1.0.1 or below. You must upgrade to 1.1.0 first.

Please read the 1.1.0 release notes below for more information.

1.1.0 (2018-06-11)

In dj-stripe 1.1.0, we made a lot of changes to models in order to bring the dj-stripe model state much closer to the upstream API objects. If you are a current user of dj-stripe, you will most likely have to make changes in order to upgrade. Please read the full changelog below. If you are having trouble upgrading, you may ask for help by filing an issue on GitHub.

1.0.0 (2017-08-12)

It’s finally here! We’ve made significant changes to the codebase and are now compliant with stripe API version 2017-06-05.

I want to give a huge thanks to all of our contributors for their help in making this happen, especially Bill Huneke (@wahuneke) for his impressive design work and @jleclanche for really pushing this release along.

I also want to welcome onboard two more maintainers, @jleclanche and @lskillen. They’ve stepped up and have graciously dedicated their resources to making dj-stripe such an amazing package.

Almost all methods now mimic the parameters of those same methods in the stripe API. Note that some methods do not have some parameters implemented. This is intentional. That being said, expect all method signatures to be different than those in previous versions of dj-stripe.

Finally, please note that there is still a bit of work ahead of us. Not everything in the Stripe API is currently supported by dj-stripe – we’re working on it. That said, v1.0.0 has been thoroughly tested and is verified stable in production applications.

0.8.0 (2015-12-30)

• better plan ordering documentation (Thanks @cjrh)

• added a confirmation page when choosing a subscription (Thanks @chrissmejia, @areski)

• setup.py reverse dependency fix (#258/#268) (Thanks @ticosax)

• Dropped official support for Django 1.7 (no code changes were made)

• Python 3.5 support, Django 1.9.1 support

• Migration improvements (Thanks @michi88)

• Fixed “Invoice matching query does not exist” bug (#263) (Thanks @mthornhill)

• Fixed duplicate content in account view (Thanks @areski)

0.7.0 (2015-09-22)

• dj-stripe now responds to the invoice.created event (Thanks @wahuneke)

• dj-stripe now cancels subscriptions and purges customers during sync if they were deleted from the stripe dashboard (Thanks @unformatt)

• dj-stripe now checks for an active stripe subscription in the update_plan_quantity call (Thanks @ctrengove)

• Event processing is now handled by “event handlers” - functions outside of models that respond to various event types and subtypes. Documentation on how to tie into the event handler system coming soon. (Thanks @wahuneke)

• Experimental Python 3.5 support

• Support for Django 1.6 and lower is now officially gone.

• Much, much more!

0.6.0 (2015-07-12)

• Support for Django 1.6 and lower is now deprecated.

• Improved test harness now tests coverage and pep8

• SubscribeFormView and ChangePlanView no longer populate self.error with form errors

• InvoiceItems.plan can now be null (as it is with individual charges), resolving #140 (Thanks @awechsler and @MichelleGlauser for help troubleshooting)

• Email templates are now packaged during distribution.

• sync_plans now takes an optional api_key

• 100% test coverage

• Stripe ID is now returned as part of each model’s str method (Thanks @areski)

• Customer model now stores card expiration month and year (Thanks @jpadilla)

• Ability to extend subscriptions (Thanks @TigerDX)

• Support for plan heirarchies (Thanks @chrissmejia)

• Rest API endpoints for Subscriptions [contrib] (Thanks @philippeluickx)

• Admin interface search by email funtionality is removed (#221) (Thanks @jpadilla)

0.5.0 (2015-05-25)

• Began deprecation of support for Django 1.6 and lower.

• Added formal support for Django 1.8.

• Removed the StripeSubscriptionSignupForm

• Removed djstripe.safe_settings. Settings are now all located in djstripe.settings

• DJSTRIPE_TRIAL_PERIOD_FOR_SUBSCRIBER_CALLBACK can no longer be a module string

• The sync_subscriber argument has been renamed from subscriber_model to subscriber

• Moved available currencies to the DJSTRIPE_CURRENCIES setting (Thanks @martinhill)

• Allow passing of extra parameters to stripe Charge API (Thanks @mthornhill)

• Support for all available arguments when syncing plans (Thanks @jamesbrobb)

• charge.refund() now returns the refunded charge object (Thanks @mthornhill)

• Charge model now has captured field and a capture method (Thanks @mthornhill)

• Subscription deleted webhook bugfix

• South migrations are now up to date (Thanks @Tyrdall)

0.4.0 (2015-04-05)

• Formal Python 3.3+/Django 1.7 Support (including migrations)

• Removed Python 2.6 from Travis CI build. (Thanks @audreyr)

• Dropped Django 1.4 support. (Thanks @audreyr)

• Deprecated the djstripe.forms.StripeSubscriptionSignupForm. Making this form work easily with both dj-stripe and django-allauth required too much abstraction. It will be removed in the 0.5.0 release.

• Add the ability to add invoice items for a customer (Thanks @kavdev)

• Add the ability to use a custom customer model (Thanks @kavdev)

• Added setting to disable Invoice receipt emails (Thanks Chris Halpert)

• Enable proration when customer upgrades plan, and pass proration policy and cancellation at period end for upgrades in settings. (Thanks Yasmine Charif)

• Removed the redundant context processor. (Thanks @kavdev)

• Fixed create a token call in change_card.html (Thanks @dollydagr)

• Fix charge.dispute.closed typo. (Thanks @ipmb)

• Fix contributing docs formatting. (Thanks @audreyr)

• Fix subscription cancelled_at_period_end field sync on plan upgrade (Thanks @nigma)

• Remove “account” bug in Middleware (Thanks @sromero84)

• Fix correct plan selection on subscription in subscribe_form template. (Thanks Yasmine Charif)

• Fix subscription status in account, _subscription_status, and cancel_subscription templates. (Thanks Yasmine Charif)

• Now using user.get_username() instead of user.username, to support custom User models. (Thanks @shvechikov)

• Update remaining DOM Ids for Bootstrap 3. (Thanks Yasmine Charif)

• Update publish command in setup.py. (Thanks @pydanny)

• Explicitly specify tox’s virtual environment names. (Thanks @audreyr)

• Manually call django.setup() to populate apps registry. (Thanks @audreyr)

0.3.5 (2014-05-01)

• Fixed djstripe_init_customers management command so it works with custom user models.

0.3.4 (2014-05-01)

• Clarify documentation for redirects on app_name.

• If settings.DEBUG is True, then django-debug-toolbar is exempt from redirect to subscription form.

• Use collections.OrderedDict to ensure that plans are listed in order of price.

• Add ordereddict library to support Python 2.6 users.

• Switch from __unicode__ to __str__ methods on models to better support Python 3.

• Add python_2_unicode_compatible decorator to Models.

• Check for PY3 so the unicode(self.user) in models.Customer doesn’t blow up in Python 3.

0.3.3 (2014-04-24)

• Increased the extendability of the views by removing as many hard-coded URLs as possible and replacing them with success_url and other attributes/methods.

• Added single unit purchasing to the cookbook

0.3.2 (2014-01-16)

• Made Yasmine Charif a core committer

• Take into account trial days in a subscription plan (Thanks Yasmine Charif)

• Correct invoice period end value (Thanks Yasmine Charif)

• Make plan cancellation and plan change consistently not prorating (Thanks Yasmine Charif)

• Fix circular import when ACCOUNT_SIGNUP_FORM_CLASS is defined (Thanks Dustin Farris)

• Add send e-mail receipt action in charges admin panel (Thanks Buddy Lindsay)

• Add created field to all ModelAdmins to help with internal auditing (Thanks Kulbir Singh)

0.3.1 (2013-11-14)

• Cancellation fix (Thanks Yasmine Charif)

• Add setup.cfg for wheel generation (Thanks Charlie Denton)

0.3.0 (2013-11-12)

• Fully tested against Django 1.6, 1.5, and 1.4

• Fix boolean default issue in models (from now on they are all default to False).

• Replace duplicated code with djstripe.utils.user_has_active_subscription.

0.2.9 (2013-09-06)

• Cancellation added to views.

• Support for kwargs on charge and invoice fetching.

• def charge() now supports send_receipt flag, default to True.

• Fixed templates to work with Bootstrap 3.0.0 column design.

0.2.8 (2013-09-02)

• Improved usage documentation.

• Corrected order of fields in StripeSubscriptionSignupForm.

• Corrected transaction history template layout.

• Updated models to take into account when settings.USE_TZ is disabled.

0.2.7 (2013-08-24)

• Add handy rest_framework permission class.

• Fixing attribution for django-stripe-payments.

• Add new status to Invoice model.

0.2.6 (2013-08-20)

• Changed name of division tag to djdiv.

• Added safe_setting.py module to handle edge cases when working with custom user models.

• Added cookbook page in the documentation.

0.2.5 (2013-08-18)

• Fixed bug in initial checkout

• You can’t purchase the same plan that you currently have.

0.2.4 (2013-08-18)

• Recursive package finding.

0.2.3 (2013-08-16)

• Fix packaging so all submodules are loaded

0.2.2 (2013-08-15)

• Added Registration + Subscription form

0.2.1 (2013-08-12)

• Fixed a bug on CurrentSubscription tests

• Improved usage documentation

• Added to migration from other tools documentation

0.2.0 (2013-08-12)

• Cancellation of plans now works.

• Upgrades and downgrades of plans now work.

• Changing of cards now works.

• Added breadcrumbs to improve navigation.

• Improved installation instructions.

• Consolidation of test instructions.

• Minor improvement to django-stripe-payments documentation

• Added coverage.py to test process.

• Added south migrations.

• Fixed the subscription_payment_required function-based view decorator.

• Removed unnecessary django-crispy-forms

0.1.7 (2013-08-08)

• Middleware excepts all of the djstripe namespaced URLs. This way people can pay.

0.1.6 (2013-08-08)

• Fixed a couple template paths

• Fixed the manifest so we include html, images.

0.1.5 (2013-08-08)

• Fixed the manifest so we include html, css, js, images.

0.1.4 (2013-08-08)

• Change PaymentRequiredMixin to SubscriptionPaymentRequiredMixin

• Add subscription_payment_required function-based view decorator

• Added SubscriptionPaymentRedirectMiddleware

• Much nicer accounts view display

• Much improved subscription form display

• Payment plans can have decimals

• Payment plans can have custom images

0.1.3 (2013-08-7)

• Added account view

• Added Customer.get_or_create method

• Added djstripe_sync_customers management command

• sync file for all code that keeps things in sync with stripe

• Use client-side JavaScript to get history data asynchronously

• More user friendly action views

0.1.2 (2013-08-6)

• Admin working

• Better publish statement

• Fix dependencies

0.1.1 (2013-08-6)

• Ported internals from django-stripe-payments

• Began writing the views

• Travis-CI

• All tests passing on Python 2.7 and 3.3

• All tests passing on Django 1.4 and 1.5

• Began model cleanup

• Better form

• Provide better response from management commands

0.1.0 (2013-08-5)

• First release on PyPI.