tarxemo-django-stripe 0.1.0

A professional Django library for integrating Stripe payments, refunds, and subscriptions

tarxemo-django-stripe

A professional, service-oriented Django library for integrating Stripe payments, refunds, and subscriptions. This library mirrors the architecture of tarxemo-django-clickpesa to provide a consistent development experience.

---

Features

• ✅ Payments (SCA Ready)
  • Easy PaymentIntent creation (for custom checkouts)
  • Full support for Stripe Checkout (hosted payment pages)
  • Automatic handling of 3DS authentication
• ✅ Subscriptions
  • Create, update, and cancel subscriptions
  • Trial period support
  • Billing portal integration (self-service for customers)
• ✅ Refunds
  • Full and partial refund support
  • Refund status tracking
• ✅ Customer Management
  • Seamless mapping of Django Users to Stripe Customers
  • Shared payment methods
• ✅ Webhooks
  • Secure signature verification
  • Idempotent processing (prevents double-processing)
  • Django Signals for all major events
• ✅ Rich Admin Dashboard
  • View all transactions, subscriptions, and events
  • Visual status badges
  • Synchronize status with a single click

---

Installation

From PyPI

pip install tarxemo-django-stripe

From Source

pip install git+https://github.com/tarxemo/tarxemo-django-stripe.git

---

Configuration

1. Register the App

Add stripe_payments to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    ...
    'stripe_payments',
]

2. Configure Credentials

Add your Stripe keys to settings.py. It is recommended to use environment variables for security.

import os

# Stripe Configuration
STRIPE_PUBLISHABLE_KEY = os.getenv('STRIPE_PUBLISHABLE_KEY')
STRIPE_SECRET_KEY = os.getenv('STRIPE_SECRET_KEY')
STRIPE_WEBHOOK_SECRET = os.getenv('STRIPE_WEBHOOK_SECRET')

3. Register Webhook URL

Add the library's URLs to your project's urls.py:

from django.urls import path, include

urlpatterns = [
    ...
    path('stripe/', include('stripe_payments.urls')),
]

4. Run Migrations

python manage.py migrate stripe_payments

---

Core Concepts

The library follows a layered architecture to keep your code clean:

1. Managers (High-level): Use these for 90% of your work. They handle business logic, database persistence, and emit Django signals.
   • PaymentManager
   • RefundManager
   • SubscriptionManager
   • CustomerManager
2. Services (Low-level): Direct wrappers for the Stripe API. Use these only if you need low-level control.
3. Signals: Decouple your app logic from payment processing by listening to events like payment_succeeded.

---

Usage Examples

1. Simple Payment (Checkout)

The quickest way to accept payments via a hosted Stripe page:

from stripe_payments import PaymentManager

manager = PaymentManager()
payment = manager.create_checkout_session(
    line_items=[{
        'price_data': {
            'currency': 'usd',
            'product_data': {'name': 'Luxury Watch'},
            'unit_amount': 25000, # $250.00
        },
        'quantity': 1,
    }],
    success_url='https://example.com/success?ref={CHECKOUT_SESSION_ID}',
    cancel_url='https://example.com/cancel',
    order_reference='ORDER-1001',
    user=request.user
)

# Redirect the user to use the hosted page
return redirect(payment.checkout_url)

2. Subscription Management

from stripe_payments import SubscriptionManager

manager = SubscriptionManager()

# Create subscription with trial
subscription = manager.create_subscription(
    user=request.user,
    price_id='price_standard_monthly',
    trial_period_days=14
)

# Open billing portal (for customers to manage their own plan)
portal_url = manager.get_billing_portal_url(
    user=request.user, 
    return_url='https://example.com/account'
)
return redirect(portal_url)

3. Listening for Events (Signals)

Decouple your business logic:

from django.dispatch import receiver
from stripe_payments.signals import payment_succeeded

@receiver(payment_succeeded)
def on_payment_success(sender, instance, **kwargs):
    # 'instance' is a StripePaymentTransaction model
    order_ref = instance.order_reference
    user = instance.user
    
    # Your fulfillment logic here
    fulfill_order(order_ref, user)

4. Processing Refunds

from stripe_payments import RefundManager

manager = RefundManager()
refund = manager.create_refund(
    order_reference='ORDER-1001',
    amount=50.00, # Partial refund
    reason='requested_by_customer'
)

---

Security Best Practices

• Never commit keys: Always use environment variables for STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET.
• Verify Signatures: This library automatically verifies all incoming webhook signatures.
• Production Key: Ensure you use sk_live_... in production. The library will warn you if it detects a test key when DEBUG=False.

---

License

MIT License. See LICENSE for details. Made with ❤️ by TarXemo.

tarxemo-django-stripe