Payments

Setup

1. Sign up for a Stripe account

2. Configure your Stripe account settings:

3. Add website URL in [Settings] > [Public Details]
4. Set logo & colors in [Settings] > [Branding]
5. Enable payment & refund emails in [Settings] > [Customer Emails]

6. Enable customer portal in [Settings] > [Customer Portal]

7. Enable Test Mode

8. Create a product and copy its price ID (format: price_1ju5GD464564) to STRIPE_PLANS in settings.py. The first price_id is used in production, the second in development/DEBUG=True mode.

   config/settings.py

   STRIPE_PLANS = [
       {
           'name': 'Your App Starter',
           'description': 'For people who want to get started with Your App',
           'price_anchor': 199,
           'price': 99,
           'features': [
               '✅ Django boilerplate',
               '✅ SEO & Blog',
               '✅ Mailgun emails',
               '✅ Stripe',
               '✅ SQLite optimized',
               '✅ Google Oauth & Magic Links',
               '✅ Components & animations',
               '❌ Lifetime updates',
           ],
           'price_id': 'price_1Px8W3HoFkHhzrx3ldgQnapM' if not DEBUG else 'price_1234',
           'coupon_id': '8acSm2ml' if not DEBUG else 'asdf',
       },
   # ...
   

   Bulk Creation via API

   Use the scripts in example.ipynb to create stripe products, prices and coupons based on your settings.py plans. Copy the generated price_ids and coupon_ids back to settings.py.

9. Get API keys from [Developers] section:

10. Add public key to STRIPE_PUBLIC_KEY in .env.local

11. Add private key to STRIPE_SECRET_KEY in .env.local

12. Set up local webhook:

    stripe listen --forward-to localhost:8000/webhook/ # do not forget the trailing slash
    

    Add the signing secret to STRIPE_WEBHOOK_SECRET in .env.local

Production Setup

1. Disable Test Mode
2. Add production API keys to .env.prod:
3. STRIPE_PUBLIC_KEY
4. STRIPE_SECRET_KEY
5. Configure production webhook:
6. URL: https://your-domain.com/webhook/ - do not forget the trailing slash
7. Required event: checkout.session.completed
8. Add webhook signing secret to STRIPE_WEBHOOK_SECRET
9. Optional: Set monthly payout date in [Balance] > [Manage Payouts]
10. Optional: Enable customer emails in [Settings] > [Customers Emails]

Stripe Events

Stripe webhook event handling

match event['type']:
    case 'checkout.session.completed':
        # First payment successful - enable access

    case 'checkout.session.expired':
        # Session expired before completion
        # Optional: Send recovery email to encourage completion

    case 'customer.subscription.updated':
        # Subscription plan changes (upgrade/downgrade/pending cancellation)

    case 'customer.subscription.deleted':
        # Subscription ended - revoke access

    case 'invoice.paid':
        # Successful payment of an invoice (e.g. a recurring payment)
        # Grant access to the product, make sure the invoice is price_id matches the plan the user is subscribed to (user.price_id)
        # Note: Preferred over 'customer.subscription.created' for subscription status
        # Ref: https://x.com/levelsio/status/1853529566490583408

    case 'invoice.payment_failed':
        # Failed payment handling options:
        # 1. Immediate access revocation
        # 2. Grace period:
        #    - Let Stripe handle automatic retry emails (Smart Retries)
        #    - Wait for 'customer.subscription.deleted' after all retries

    case _:
        # Unhandled event type