Subscription Billing System

Data Model: User vs Customer

Never mix Auth data with Billing data. Keep them loosely coupled.

Subscription Lifecycle (State Machine)

Billing logic is complex. Model it as a Finite State Machine (FSM) to handle transitions deterministically.

Idempotency & Webhooks

Payment gateways send webhooks (e.g., invoice.paid) asynchronously. Network issues can cause duplicate events. Your handler MUST be Idempotent.

# Python (Flask) Example: Handling Stripe Webhooks safely
import stripe
from flask import Flask, request, jsonify

@app.route('/webhook', methods=['POST'])
def stripe_webhook():
    payload = request.data
    sig_header = request.headers['Stripe-Signature']
    event = None

    try:
        # 1. Verify Signature (Security)
        event = stripe.Webhook.construct_event(payload, sig_header, endpoint_secret)
    except ValueError:
        return 'Invalid payload', 400

    # 2. Idempotency Check (Redis/DB)
    event_id = event['id']
    if redis.exists(f"processed_event:{event_id}"):
        return jsonify({'status': 'ignored - duplicate'}), 200

    # 3. Process Event based on Type
    if event['type'] == 'invoice.payment_succeeded':
        handle_payment_success(event['data']['object'])
    
    # 4. Mark as Processed (TTL 24h)
    redis.set(f"processed_event:{event_id}", "true", ex=86400)
    
    return jsonify({'status': 'success'}), 200

PCI Compliance (SAQ A)

Never let raw Credit Card numbers touch your servers. If they hit your API logs, you are liable.