The payments app includes logic for handling subscription payments with stripe.

Basic Concepts

Managing the business logic/workflow for subscriptions can be complex. The Vanty solves this by providing a clear interface for managing the state of the subscription at any given time.

Business Logic/Subscriptions workflow

See payments/

  • The app uses a finite state model (fsm via the django_fsm library) to easily manage business logic relating to subscription flows.
  • Business Logic for the payments is encapsulated in the SubscriptionPaymentsMixin class.
  • Use the class to easily manage how each subscription transitions between different states e.g. from trialing to active
  • You can also include any side effects here, for example mailing a customer after successful payment, activating a product.
  • The SubscriptionPaymentsMixin is an abstract class that inherits from models.Model
  • This means that no database table is created for this class during migration, instead, each subscription is attached to a tenant. (see [multitenancy/workspaces docs](apps/tenants))
  • This makes it easier to transfer ownership of workspaces between users or manage billing usage for an organization.
  • You could also choose to attach each subscription to another entity, for example, a user for example.

Product metadata for UI

Product metadata e.g. features, descriptions can either be stored on the database or defined in code. The preferred method for the Vanty is to use the database for product metadata.

Information about active subscription products is stored in a cached model ( see apps/dashboard/ ). This information is exposed to the frontend templates via a context processor, see apps/common/

You could also opt to include prices on a static file but this means having to manually update the prices every time you change the price on the dashboard.

Settings Configuration for Stripe

To start using Stripe to collect payments you’ll need to fill in the following in config/settings/ or populate them in the appropriate environment variables. Since version 0.8.0, stripe secret keys, products can be updated directly from the dashboard. Please note that when you first start, you will still need to add the Stripe API keys to your environment.

STRIPE_LIVE_PUBLIC_KEY = env("STRIPE_LIVE_PUBLIC_KEY", default="<your publishable key>")
STRIPE_LIVE_SECRET_KEY = env("STRIPE_LIVE_SECRET_KEY", default="<your secret key>")
STRIPE_TEST_PUBLIC_KEY = env("STRIPE_TEST_PUBLIC_KEY", default="<your publishable key>")
STRIPE_TEST_SECRET_KEY = env("STRIPE_TEST_SECRET_KEY", default="<your secret key>")
STRIPE_LIVE_MODE = False  # Change to True in production
    "DJSTRIPE_WEBHOOK_SECRET", default="whsec_yourwebhok"
) # required

Your webhook secret can be found on the stripe dashboard.

Products and checkout session setup

  • At minimum you will have to set up some products and attach prices to those products. The products can be added from the stripe dashboard .

  • The app relies on stripe checkout to manage card payments etc. This means stripe will handle everything including fraud checks, customer data security, etc so you can focus on your business. See here for more info about the stripe checkout.

  • Billing management is also handled by stripe via the customer portal. You will have to add/update your customer portal settings here .

Modelling your products

[since version 0.10.0]

There are two types of price models for recurring purchases, licensed or metered. Licensed usage model can be configured from the dashboard.

  • Standard: Flat (licensed) : A Workspace/Tenant has unlimited users and gets charged flat fee a month.

  • Default. No changes required.

  • Standard: Per seat (licensed) Limit the number of users per tenant based on the number of seats. Users can modify seats during checkout.

  • *Package: Per set of users (5 users @ $50 per month) (licensed) . Users can modify seats during checkout. First batch of 5 users is $50. Next user till 10 i.e. 6-10 will raise monthly price to $100.

[Utilities on next release 0.10.1]

  • Volume Pricing (metered): Charged at per same for each unit based on number of units sold.

  • Graduated Pricing (metered): Charged at different rates

Payment Processing

Once a user selects a product, a stripe checkout session is created and they are automatically redirected to the stripe. The app keeps track of all active checkout sessions

Sessions will remain active for at least 24 hours unless explicitly canceled by users.

The app & API only include basic views to trigger/manage new stripe checkout sessions. This is by design as session checkout management is delegated to stripe.

Standard emails are included for managing communication of subscription information/events with end-users. These can be modified, see templates/templated_email/payments/ .

Testing your payments workflow

  • The test suit includes unit testing for the payments checkout flow with the stripe webhooks responses mocked.

  • You will want to test with live data in your test environment to test webhooks, follow the links on your stripe dashboard to install the stripe cli and configure webhooks.

    # install stripe
    pip install stripe-cli
    # login
    stripe login
    # listen to webhooks
    stripe listen --forward-to=localhost:8000/billing/webhooks/
    ⡿ Checking for new versions... A newer version of the Stripe CLI is available, please update to: v1.8.1
    ⣽ Getting ready... > Ready! Your webhook signing secret is whsec_xxxx
  • copy the webhook secret to your settings file.