vanty-payments 0.3.0

Vanty App: Stripe customers, catalog, checkout, billing, usage, credits, webhooks.

Vanty Payments

Stripe-first payments toolkit for FastAPI with Tortoise ORM. Checkout, subscriptions, invoices, billing portal, webhooks, and full Stripe object sync in a single pip install.

Installation

pip install vanty-payments
# or
uv pip install vanty-payments

Quick start

from contextlib import asynccontextmanager

from fastapi import FastAPI

from vanty_payments import PaymentsSettings, mount_payments_router

settings = PaymentsSettings(
    database_url="sqlite://./vanty-payments.db",
    stripe_test_secret_key="sk_test_example",
    stripe_webhook_secret="whsec_example",
)

app = FastAPI()
kit = mount_payments_router(app, settings=settings)


@asynccontextmanager
async def lifespan(_: FastAPI):
    await kit.init_orm(generate_schemas=True)
    try:
        yield
    finally:
        await kit.close_orm()


app.router.lifespan_context = lifespan

Run with uvicorn main:app --reload and visit /docs for the interactive API explorer.

Features

• Checkout sessions with Stripe-hosted and embedded flows
• Subscription management with plan changes, cancellation, and reactivation
• Invoice management with PDF links and payment status tracking
• Billing portal sessions for customer self-service
• Payment method management (cards, bank accounts)
• Webhook ingestion with signature verification and idempotent processing
• Manual sync to pull Stripe state into local models on demand
• Full Stripe object coverage including customers, products, prices, coupons, promotion codes, discounts, charges, refunds, disputes, and more
• Admin management endpoints for super-admin billing operations
• Identity integration with custom identity resolvers

Architecture

PaymentsApp is a composition root that wires all services. Access services directly:

kit = mount_payments_router(app, settings=settings)

# Direct service access
await kit.checkout_service.create_session(customer_id=cid, price_id=pid)
await kit.subscription_service.list_subscriptions(customer_id=cid)
await kit.sync_service.sync_customer(stripe_customer_id="cus_xxx")

Available services on PaymentsApp:

Service	Purpose
customer_service	Customer bootstrap and management
checkout_service	Checkout session creation
subscription_service	Subscription reads and management
invoice_service	Invoice listing and retrieval
payment_method_service	Payment method listing
portal_service	Billing portal session creation
webhook_service	Webhook signature verification and dispatch
sync_service	Manual Stripe-to-local sync for all object types
admin_service	Super-admin billing operations

Configuration

All settings are read from environment variables with the PAYMENTS_KIT_ prefix, or passed directly to PaymentsSettings.

Setting	Default	Description
database_url	sqlite://./vanty-payments.db	Tortoise ORM database URL
stripe_test_secret_key	—	Stripe test mode secret key
stripe_live_secret_key	—	Stripe live mode secret key
stripe_webhook_secret	—	Webhook endpoint signing secret
stripe_mode	test	test or live
default_currency	usd	Default currency for new prices

Set via environment: PAYMENTS_KIT_STRIPE_TEST_SECRET_KEY=sk_test_... PAYMENTS_KIT_DATABASE_URL=postgres://...

API surface

Public routes (/payments)

Method	Path	Description
POST	/customers/bootstrap	Create or retrieve a Stripe customer
GET	/catalog/products	List available products
GET	/catalog/prices	List prices for a product
POST	/checkout/sessions	Create a checkout session
GET	/subscriptions	List subscriptions
GET	/subscriptions/{id}	Get subscription details
POST	/subscriptions/{id}/cancel	Cancel a subscription
POST	/portal/sessions	Create a billing portal session
GET	/invoices	List invoices
GET	/invoices/{id}	Get invoice details
GET	/payment-methods	List payment methods
POST	/webhooks/stripe	Stripe webhook endpoint
POST	/sync	Trigger manual sync

Admin routes (/admin/payments)

Super-admin endpoints for platform-wide billing management. Mount separately:

app.include_router(kit.admin_router, prefix="/admin/payments")

Host app identity integration

The package works standalone, but a host app can supply a request-level identity adapter through app.state.payments_identity_resolver:

async def resolve_identity(request: Request) -> IdentityContext:
    return IdentityContext(
        user_reference=request.state.user_id,
        organization_reference=request.state.org_id,
    )

app.state.payments_identity_resolver = resolve_identity

Routes then use those references automatically when request payloads omit them.

Project layout

src/vanty_payments/       Package source
docs/                     Documentation
examples/reference-api/   Reference FastAPI application
tests/                    pytest suite (unit + integration)

Development

git clone https://github.com/advantch/vanty-payments.git
cd vanty-payments
uv sync --dev

# Lint
uv run ruff check

# Test
uv run pytest -q

# Run reference API
cd examples/reference-api && uv run uvicorn main:app --reload

Use uv run pytest --no-cov tests/path/to/test.py for targeted debugging without the coverage gate.

Releasing

Tags trigger the release workflow. The GitHub Actions pipeline builds, creates a GitHub release, and publishes to PyPI automatically.

git tag v0.2.0
git push origin v0.2.0

License

MIT