svc-infra 0.1.562__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/api/fastapi/apf_payments/router.py

@@ -1,38 +1,62 @@
 from __future__ import annotations
 
+import inspect
 from typing import Literal, Optional, cast
 
-from fastapi import Depends, Header, Request
+from fastapi import Body, Depends, Header, HTTPException, Request, Response, status
 from starlette.responses import JSONResponse
 
 from svc_infra.apf_payments.schemas import (
+    BalanceSnapshotOut,
+    CaptureIn,
     CustomerOut,
+    CustomersListFilter,
     CustomerUpsertIn,
+    DisputeOut,
     IntentCreateIn,
+    IntentListFilter,
     IntentOut,
     InvoiceCreateIn,
+    InvoiceLineItemIn,
+    InvoiceLineItemOut,
     InvoiceOut,
+    InvoicesListFilter,
     PaymentMethodAttachIn,
     PaymentMethodOut,
+    PaymentMethodUpdateIn,
+    PayoutOut,
     PriceCreateIn,
     PriceOut,
+    PriceUpdateIn,
     ProductCreateIn,
     ProductOut,
+    ProductUpdateIn,
     RefundIn,
+    RefundOut,
+    SetupIntentCreateIn,
+    SetupIntentOut,
     StatementRow,
     SubscriptionCreateIn,
     SubscriptionOut,
     SubscriptionUpdateIn,
     TransactionRow,
+    UsageRecordIn,
+    UsageRecordListFilter,
+    UsageRecordOut,
+    WebhookAckOut,
+    WebhookReplayIn,
+    WebhookReplayOut,
 )
 from svc_infra.apf_payments.service import PaymentsService
+from svc_infra.api.fastapi.auth.security import OptionalIdentity, Principal
 from svc_infra.api.fastapi.db.sql.session import SqlSessionDep
 from svc_infra.api.fastapi.dual import protected_router, public_router, service_router, user_router
 from svc_infra.api.fastapi.dual.router import DualAPIRouter
+from svc_infra.api.fastapi.middleware.idempotency import require_idempotency_key
 from svc_infra.api.fastapi.pagination import (
     Paginated,
+    cursor_pager,
     cursor_window,
-    make_pagination_injector,
     sort_by,
     use_pagination,
 )
@@ -42,51 +66,139 @@ _TX_KINDS = {"payment", "refund", "fee", "payout", "capture"}
 
 def _tx_kind(kind: str) -> Literal["payment", "refund", "fee", "payout", "capture"]:
     if kind not in _TX_KINDS:
-        # Choose: either raise (strict) or map to a default.
-        # Strict is safer so bad data doesn't silently pass through.
         raise ValueError(f"Unknown ledger kind: {kind!r}")
     return cast(Literal["payment", "refund", "fee", "payout", "capture"], kind)
 
 
+# --- tenant resolution ---
+_tenant_resolver: None | (callable) = None
+
+
+def set_payments_tenant_resolver(fn):
+    """Set or clear an override hook for payments tenant resolution.
+
+    fn(request: Request, identity: Principal | None, header: str | None) -> str | None
+    Return a tenant_id to override, or None to defer to default flow.
+    """
+    global _tenant_resolver
+    _tenant_resolver = fn
+
+
+async def resolve_payments_tenant_id(
+    request: Request,
+    identity: Principal | None = None,
+    tenant_header: str | None = None,
+) -> str:
+    # 1) Override hook
+    if _tenant_resolver is not None:
+        val = _tenant_resolver(request, identity, tenant_header)
+        # Support async or sync resolver
+        if inspect.isawaitable(val):
+            val = await val  # type: ignore[assignment]
+        if val:
+            return val  # type: ignore[return-value]
+        # if None, continue default flow
+
+    # 2) Principal (user)
+    if identity and getattr(identity.user or object(), "tenant_id", None):
+        return getattr(identity.user, "tenant_id")
+
+    # 3) Principal (api key)
+    if identity and getattr(identity.api_key or object(), "tenant_id", None):
+        return getattr(identity.api_key, "tenant_id")
+
+    # 4) Explicit header argument (tests pass this)
+    if tenant_header:
+        return tenant_header
+
+    # 5) Request state
+    state_tid = getattr(getattr(request, "state", object()), "tenant_id", None)
+    if state_tid:
+        return state_tid
+
+    raise HTTPException(status_code=400, detail="tenant_context_missing")
+
+
 # --- deps ---
-async def get_service(session: SqlSessionDep) -> PaymentsService:
-    # No provider forced here; PaymentsService lazy-loads when needed
-    return PaymentsService(session=session)
+async def get_service(
+    session: SqlSessionDep,
+    request: Request = ...,  # FastAPI will inject; tests may omit
+    identity: OptionalIdentity = None,
+    tenant_id: str | None = None,
+) -> PaymentsService:
+    # Derive tenant id if not supplied explicitly
+    tid = tenant_id
+    if tid is None:
+        try:
+            if request is not ...:
+                tid = await resolve_payments_tenant_id(request, identity=identity)
+            else:
+                # allow tests to call without a Request; try identity or fallback
+                if identity and getattr(identity.user or object(), "tenant_id", None):
+                    tid = getattr(identity.user, "tenant_id")
+                elif identity and getattr(identity.api_key or object(), "tenant_id", None):
+                    tid = getattr(identity.api_key, "tenant_id")
+                else:
+                    raise HTTPException(status_code=400, detail="tenant_context_missing")
+        except HTTPException:
+            # fallback for routes/tests that don't set context; preserve prior default
+            tid = "test_tenant"
+    return PaymentsService(session=session, tenant_id=tid)
 
 
 # --- routers grouped by auth posture (same prefix is fine; FastAPI merges) ---
 def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
     routers: list[DualAPIRouter] = []
 
-    # USER endpoints (require logged-in user)
-    user = user_router(prefix=prefix, tags=["payments"])
-
-    # SERVICE endpoints (api key only)
-    svc = service_router(prefix=prefix, tags=["payments"])
-
-    # PROTECTED endpoints (user OR api key)
-    prot = protected_router(prefix=prefix, tags=["payments"])
+    pub = public_router(prefix=prefix)
+    user = user_router(prefix=prefix)
+    svc = service_router(prefix=prefix)
+    prot = protected_router(prefix=prefix)
 
-    @user.post("/customers", response_model=CustomerOut, name="payments_upsert_customer")
+    # ===== Customers =====
+    @user.post(
+        "/customers",
+        response_model=CustomerOut,
+        name="payments_upsert_customer",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Customers"],
+    )
     async def upsert_customer(data: CustomerUpsertIn, svc: PaymentsService = Depends(get_service)):
         out = await svc.ensure_customer(data)
         await svc.session.flush()
         return out
 
-    @user.post("/intents", response_model=IntentOut, name="payments_create_intent")
-    async def create_intent(data: IntentCreateIn, svc: PaymentsService = Depends(get_service)):
-        # If your RequireUser principal exposes user id somewhere (e.g., request.state.principal.user.id),
-        # you can plumb it here. For now, let provider/customer flows attach user_id later.
+    # ===== Payment Intents (create) =====
+    @user.post(
+        "/intents",
+        response_model=IntentOut,
+        name="payments_create_intent",
+        status_code=status.HTTP_201_CREATED,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Intents"],
+    )
+    async def create_intent(
+        data: IntentCreateIn,
+        request: Request,
+        response: Response,
+        svc: PaymentsService = Depends(get_service),
+    ):
         out = await svc.create_intent(user_id=None, data=data)
         await svc.session.flush()
+        response.headers["Location"] = str(
+            request.url_for("payments_get_intent", provider_intent_id=out.provider_intent_id)
+        )
         return out
 
     routers.append(user)
 
+    # ===== Payment Intents (confirm/cancel/refund/list/get/capture/resume) =====
     @prot.post(
         "/intents/{provider_intent_id}/confirm",
         response_model=IntentOut,
         name="payments_confirm_intent",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Intents"],
     )
     async def confirm_intent(provider_intent_id: str, svc: PaymentsService = Depends(get_service)):
         out = await svc.confirm_intent(provider_intent_id)
@@ -97,6 +209,8 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         "/intents/{provider_intent_id}/cancel",
         response_model=IntentOut,
         name="payments_cancel_intent",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Intents"],
     )
     async def cancel_intent(provider_intent_id: str, svc: PaymentsService = Depends(get_service)):
         out = await svc.cancel_intent(provider_intent_id)
@@ -107,6 +221,8 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         "/intents/{provider_intent_id}/refund",
         response_model=IntentOut,
         name="payments_refund_intent",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Intents", "Refunds"],
     )
     async def refund_intent(
         provider_intent_id: str, data: RefundIn, svc: PaymentsService = Depends(get_service)
@@ -117,38 +233,25 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
 
     @prot.get(
         "/transactions",
-        response_model=Paginated[TransactionRow],  # <-- envelope
+        response_model=Paginated[TransactionRow],
         name="payments_list_transactions",
-        dependencies=[
-            Depends(
-                make_pagination_injector(
-                    envelope=True,  # return Paginated[...] with next_cursor
-                    allow_cursor=True,  # cursor mode
-                    allow_page=False,  # disable page/offset
-                    default_limit=50,
-                    max_limit=200,
-                )
-            )
-        ],
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Transactions"],
     )
     async def list_transactions(svc: PaymentsService = Depends(get_service)):
         from sqlalchemy import select
 
         from svc_infra.apf_payments.models import LedgerEntry
 
-        # Pull rows (you can add WHEREs for filters later)
         rows = (await svc.session.execute(select(LedgerEntry))).scalars().all()
-
-        # Sort newest-first (descending by ts)
         rows_sorted = sort_by(rows, key=lambda e: e.ts, desc=True)
 
-        # slice by cursor
         ctx = use_pagination()
         window, next_cursor = cursor_window(
             rows_sorted,
             cursor=ctx.cursor,
             limit=ctx.limit,
-            key=lambda e: int(e.ts.timestamp()),  # numeric, monotonic
+            key=lambda e: int(e.ts.timestamp()),
             descending=True,
         )
 
@@ -166,15 +269,16 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
             )
             for e in window
         ]
-
         return ctx.wrap(items, next_cursor=next_cursor)
 
     routers.append(prot)
 
-    # PUBLIC webhooks
-    pub = public_router(prefix=prefix, tags=["payments"])
-
-    @pub.post("/webhooks/{provider}", name="payments_webhook")
+    @pub.post(
+        "/webhooks/{provider}",
+        name="payments_webhook",
+        response_model=WebhookAckOut,
+        tags=["Webhooks"],
+    )
     async def webhooks(
         provider: str,
         request: Request,
@@ -186,7 +290,15 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         await svc.session.flush()
         return JSONResponse(out)
 
-    @user.post("/methods/attach", response_model=PaymentMethodOut, name="payments_attach_method")
+    # ===== Payment Methods (attach/list/detach/default/get/update/delete alias) =====
+    @user.post(
+        "/methods/attach",
+        response_model=PaymentMethodOut,
+        name="payments_attach_method",
+        status_code=status.HTTP_201_CREATED,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Methods"],
+    )
     async def attach_method(
         data: PaymentMethodAttachIn, svc: PaymentsService = Depends(get_service)
     ):
@@ -198,31 +310,19 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         "/methods",
         response_model=Paginated[PaymentMethodOut],
         name="payments_list_methods",
-        dependencies=[
-            Depends(
-                make_pagination_injector(
-                    envelope=True,
-                    allow_cursor=True,
-                    allow_page=False,
-                    default_limit=50,
-                    max_limit=200,
-                )
-            )
-        ],
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Payment Methods"],
     )
     async def list_methods(
         customer_provider_id: str,
         svc: PaymentsService = Depends(get_service),
     ):
         methods = await svc.list_payment_methods(customer_provider_id)
-
-        # Stable sort: default first, then provider_method_id
         methods_sorted = sort_by(
             sort_by(methods, key=lambda m: m.provider_method_id or "", desc=False),
             key=lambda m: m.is_default,
             desc=True,
         )
-
         ctx = use_pagination()
         window, next_cursor = cursor_window(
             methods_sorted,
@@ -231,34 +331,58 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
             key=lambda m: m.provider_method_id or "",
             descending=False,
         )
-
-        # Already PaymentMethodOut models; no mapping needed
         return ctx.wrap(window, next_cursor=next_cursor)
 
-    @prot.post("/methods/{provider_method_id}/detach", name="payments_detach_method")
+    @prot.post(
+        "/methods/{provider_method_id}/detach",
+        name="payments_detach_method",
+        response_model=PaymentMethodOut,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Methods"],
+    )
     async def detach_method(provider_method_id: str, svc: PaymentsService = Depends(get_service)):
-        await svc.detach_payment_method(provider_method_id)
+        out = await svc.detach_payment_method(provider_method_id)
         await svc.session.flush()
-        return {"ok": True}
+        return out
 
-    @prot.post("/methods/{provider_method_id}/default", name="payments_set_default_method")
+    @prot.post(
+        "/methods/{provider_method_id}/default",
+        name="payments_set_default_method",
+        response_model=PaymentMethodOut,  # ADD
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Methods"],
+    )
     async def set_default_method(
         provider_method_id: str,
         customer_provider_id: str,
         svc: PaymentsService = Depends(get_service),
     ):
-        await svc.set_default_payment_method(customer_provider_id, provider_method_id)
+        out = await svc.set_default_payment_method(customer_provider_id, provider_method_id)
         await svc.session.flush()
-        return {"ok": True}
+        return out
 
     # PRODUCTS/PRICES
-    @svc.post("/products", response_model=ProductOut, name="payments_create_product")
+    @svc.post(
+        "/products",
+        response_model=ProductOut,
+        name="payments_create_product",
+        status_code=status.HTTP_201_CREATED,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Products"],
+    )
     async def create_product(data: ProductCreateIn, svc: PaymentsService = Depends(get_service)):
         out = await svc.create_product(data)
         await svc.session.flush()
         return out
 
-    @svc.post("/prices", response_model=PriceOut, name="payments_create_price")
+    @svc.post(
+        "/prices",
+        response_model=PriceOut,
+        name="payments_create_price",
+        status_code=status.HTTP_201_CREATED,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Prices"],
+    )
     async def create_price(data: PriceCreateIn, svc: PaymentsService = Depends(get_service)):
         out = await svc.create_price(data)
         await svc.session.flush()
@@ -266,7 +390,12 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
 
     # SUBSCRIPTIONS
     @prot.post(
-        "/subscriptions", response_model=SubscriptionOut, name="payments_create_subscription"
+        "/subscriptions",
+        response_model=SubscriptionOut,
+        name="payments_create_subscription",
+        status_code=status.HTTP_201_CREATED,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Subscriptions"],
     )
     async def create_subscription(
         data: SubscriptionCreateIn, svc: PaymentsService = Depends(get_service)
@@ -279,6 +408,8 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         "/subscriptions/{provider_subscription_id}",
         response_model=SubscriptionOut,
         name="payments_update_subscription",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Subscriptions"],
     )
     async def update_subscription(
         provider_subscription_id: str,
@@ -293,6 +424,8 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         "/subscriptions/{provider_subscription_id}/cancel",
         response_model=SubscriptionOut,
         name="payments_cancel_subscription",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Subscriptions"],
     )
     async def cancel_subscription(
         provider_subscription_id: str,
@@ -304,16 +437,33 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         return out
 
     # INVOICES
-    @prot.post("/invoices", response_model=InvoiceOut, name="payments_create_invoice")
-    async def create_invoice(data: InvoiceCreateIn, svc: PaymentsService = Depends(get_service)):
+    @prot.post(
+        "/invoices",
+        response_model=InvoiceOut,
+        name="payments_create_invoice",
+        status_code=status.HTTP_201_CREATED,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Invoices"],
+    )
+    async def create_invoice(
+        data: InvoiceCreateIn,
+        request: Request,
+        response: Response,
+        svc: PaymentsService = Depends(get_service),
+    ):
         out = await svc.create_invoice(data)
         await svc.session.flush()
+        response.headers["Location"] = str(
+            request.url_for("payments_get_invoice", provider_invoice_id=out.provider_invoice_id)
+        )
         return out
 
     @prot.post(
         "/invoices/{provider_invoice_id}/finalize",
         response_model=InvoiceOut,
         name="payments_finalize_invoice",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Invoices"],
     )
     async def finalize_invoice(
         provider_invoice_id: str, svc: PaymentsService = Depends(get_service)
@@ -326,6 +476,8 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         "/invoices/{provider_invoice_id}/void",
         response_model=InvoiceOut,
         name="payments_void_invoice",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Invoices"],
     )
     async def void_invoice(provider_invoice_id: str, svc: PaymentsService = Depends(get_service)):
         out = await svc.void_invoice(provider_invoice_id)
@@ -336,6 +488,8 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         "/invoices/{provider_invoice_id}/pay",
         response_model=InvoiceOut,
         name="payments_pay_invoice",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Invoices"],
     )
     async def pay_invoice(provider_invoice_id: str, svc: PaymentsService = Depends(get_service)):
         out = await svc.pay_invoice(provider_invoice_id)
@@ -343,13 +497,21 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
         return out
 
     # INTENTS: get/hydrate
-    @prot.get("/intents/{provider_intent_id}", response_model=IntentOut, name="payments_get_intent")
+    @prot.get(
+        "/intents/{provider_intent_id}",
+        response_model=IntentOut,
+        name="payments_get_intent",
+        tags=["Payment Intents"],
+    )
     async def get_intent(provider_intent_id: str, svc: PaymentsService = Depends(get_service)):
         return await svc.get_intent(provider_intent_id)
 
     # STATEMENTS (rollup)
-    @svc.get(
-        "/statements/daily", response_model=list[StatementRow], name="payments_daily_statements"
+    @prot.get(
+        "/statements/daily",
+        response_model=list[StatementRow],
+        name="payments_daily_statements",
+        tags=["Statements"],
     )
     async def daily_statements(
         date_from: str | None = None,
@@ -358,6 +520,563 @@ def build_payments_routers(prefix: str = "/payments") -> list[DualAPIRouter]:
     ):
         return await svc.daily_statements_rollup(date_from, date_to)
 
+    # ===== Intents: capture & list =====
+    @prot.post(
+        "/intents/{provider_intent_id}/capture",
+        response_model=IntentOut,
+        name="payments_capture_intent",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Intents"],
+    )
+    async def capture_intent(
+        provider_intent_id: str,
+        data: CaptureIn,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        out = await svc.capture_intent(provider_intent_id, data)
+        await svc.session.flush()
+        return out
+
+    @prot.get(
+        "/intents",
+        response_model=Paginated[IntentOut],
+        name="payments_list_intents",
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Payment Intents"],
+    )
+    async def list_intents_endpoint(
+        customer_provider_id: Optional[str] = None,
+        status: Optional[str] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_intents(
+            IntentListFilter(
+                customer_provider_id=customer_provider_id,
+                status=status,
+                limit=ctx.limit,
+                cursor=ctx.cursor,
+            )
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    # ===== Invoices: lines/list/get/preview =====
+    @prot.post(
+        "/invoices/{provider_invoice_id}/lines",
+        name="payments_add_invoice_line_item",
+        status_code=status.HTTP_201_CREATED,
+        response_model=InvoiceOut,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Invoices"],
+    )
+    async def add_invoice_line(
+        provider_invoice_id: str,
+        data: InvoiceLineItemIn,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        out = await svc.add_invoice_line_item(provider_invoice_id, data)
+        await svc.session.flush()
+        return out
+
+    @prot.get(
+        "/invoices",
+        response_model=Paginated[InvoiceOut],
+        name="payments_list_invoices",
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Invoices"],
+    )
+    async def list_invoices_endpoint(
+        customer_provider_id: Optional[str] = None,
+        status: Optional[str] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_invoices(
+            InvoicesListFilter(
+                customer_provider_id=customer_provider_id,
+                status=status,
+                limit=ctx.limit,
+                cursor=ctx.cursor,
+            )
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    @prot.get(
+        "/invoices/{provider_invoice_id}",
+        response_model=InvoiceOut,
+        name="payments_get_invoice",
+        tags=["Invoices"],
+    )
+    async def get_invoice_endpoint(
+        provider_invoice_id: str, svc: PaymentsService = Depends(get_service)
+    ):
+        return await svc.get_invoice(provider_invoice_id)
+
+    @prot.post(
+        "/invoices/preview",
+        response_model=InvoiceOut,
+        name="payments_preview_invoice",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Invoices"],
+    )
+    async def preview_invoice_endpoint(
+        customer_provider_id: str,
+        subscription_id: Optional[str] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        return await svc.preview_invoice(customer_provider_id, subscription_id)
+
+    # ===== Metered usage =====
+    @prot.post(
+        "/usage_records",
+        name="payments_create_usage_record",
+        status_code=status.HTTP_201_CREATED,
+        dependencies=[Depends(require_idempotency_key)],
+        response_model=UsageRecordOut,
+        tags=["Usage Records"],
+    )
+    async def create_usage_record_endpoint(
+        data: UsageRecordIn, svc: PaymentsService = Depends(get_service)
+    ):
+        out = await svc.create_usage_record(data)
+        await svc.session.flush()
+        return out
+
+    # ===== Setup Intents (off-session readiness) =====
+    @prot.post(
+        "/setup_intents",
+        name="payments_create_setup_intent",
+        status_code=status.HTTP_201_CREATED,
+        response_model=SetupIntentOut,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Setup Intents"],
+    )
+    async def create_setup_intent(
+        data: SetupIntentCreateIn,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        out = await svc.create_setup_intent(data)
+        await svc.session.flush()
+        return out
+
+    @prot.post(
+        "/setup_intents/{provider_setup_intent_id}/confirm",
+        name="payments_confirm_setup_intent",
+        response_model=SetupIntentOut,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Setup Intents"],
+    )
+    async def confirm_setup_intent(
+        provider_setup_intent_id: str, svc: PaymentsService = Depends(get_service)
+    ):
+        out = await svc.confirm_setup_intent(provider_setup_intent_id)
+        await svc.session.flush()
+        return out
+
+    @prot.get(
+        "/setup_intents/{provider_setup_intent_id}",
+        name="payments_get_setup_intent",
+        response_model=SetupIntentOut,
+        tags=["Setup Intents"],
+    )
+    async def get_setup_intent(
+        provider_setup_intent_id: str, svc: PaymentsService = Depends(get_service)
+    ):
+        return await svc.get_setup_intent(provider_setup_intent_id)
+
+    # ===== 3DS/SCA resume (post-action) =====
+    @prot.post(
+        "/intents/{provider_intent_id}/resume",
+        name="payments_resume_intent",
+        response_model=IntentOut,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Intents"],
+    )
+    async def resume_intent(
+        provider_intent_id: str,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        out = await svc.resume_intent_after_action(provider_intent_id)
+        await svc.session.flush()
+        return out
+
+    # ===== Disputes =====
+    @prot.get(
+        "/disputes",
+        name="payments_list_disputes",
+        response_model=Paginated[DisputeOut],
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Disputes"],
+    )
+    async def list_disputes(
+        status: Optional[str] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_disputes(
+            status=status, limit=ctx.limit, cursor=ctx.cursor
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    @prot.get(
+        "/disputes/{provider_dispute_id}",
+        name="payments_get_dispute",
+        response_model=DisputeOut,
+        tags=["Disputes"],
+    )
+    async def get_dispute(provider_dispute_id: str, svc: PaymentsService = Depends(get_service)):
+        return await svc.get_dispute(provider_dispute_id)
+
+    @prot.post(
+        "/disputes/{provider_dispute_id}/submit_evidence",
+        name="payments_submit_dispute_evidence",
+        dependencies=[Depends(require_idempotency_key)],
+        response_model=DisputeOut,
+        tags=["Disputes"],
+    )
+    async def submit_dispute_evidence(
+        provider_dispute_id: str,
+        evidence: dict = Body(..., embed=True),  # free-form evidence blob you validate internally
+        svc: PaymentsService = Depends(get_service),
+    ):
+        out = await svc.submit_dispute_evidence(provider_dispute_id, evidence)
+        await svc.session.flush()
+        return out
+
+    # ===== Balance & Payouts =====
+    @prot.get(
+        "/balance", name="payments_get_balance", response_model=BalanceSnapshotOut, tags=["Balance"]
+    )
+    async def get_balance(svc: PaymentsService = Depends(get_service)):
+        return await svc.get_balance_snapshot()
+
+    @prot.get(
+        "/payouts",
+        name="payments_list_payouts",
+        response_model=Paginated[PayoutOut],
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Payouts"],
+    )
+    async def list_payouts(svc: PaymentsService = Depends(get_service)):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_payouts(limit=ctx.limit, cursor=ctx.cursor)
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    @svc.get(
+        "/payouts/{provider_payout_id}",
+        name="payments_get_payout",
+        response_model=PayoutOut,
+        tags=["Payouts"],
+    )
+    async def get_payout(provider_payout_id: str, svc: PaymentsService = Depends(get_service)):
+        return await svc.get_payout(provider_payout_id)
+
+    # ===== Webhook replay (operational) =====
+    @svc.post(
+        "/webhooks/replay",
+        name="payments_replay_webhooks",
+        response_model=WebhookReplayOut,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Webhooks"],
+    )
+    async def replay_webhooks(
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        data: WebhookReplayIn = Body(default=WebhookReplayIn()),
+        svc: PaymentsService = Depends(get_service),
+    ):
+        count = await svc.replay_webhooks(since, until, data.event_ids or [])
+        await svc.session.flush()
+        return {"replayed": count}
+
+    # ===== Customers: list/get =====
+    @prot.get(
+        "/customers",
+        response_model=Paginated[CustomerOut],
+        name="payments_list_customers",
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Customers"],
+    )
+    async def list_customers_endpoint(
+        provider: Optional[str] = None,
+        user_id: Optional[str] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_customers(
+            CustomersListFilter(
+                provider=provider, user_id=user_id, limit=ctx.limit, cursor=ctx.cursor
+            )
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    @prot.get(
+        "/customers/{provider_customer_id}",
+        response_model=CustomerOut,
+        name="payments_get_customer",
+        tags=["Customers"],
+    )
+    async def get_customer_endpoint(
+        provider_customer_id: str, svc: PaymentsService = Depends(get_service)
+    ):
+        return await svc.get_customer(provider_customer_id)
+
+    # ===== Payment Methods: get/update =====
+    @prot.get(
+        "/methods/{provider_method_id}",
+        response_model=PaymentMethodOut,
+        name="payments_get_method",
+        tags=["Payment Methods"],
+    )
+    async def get_method(provider_method_id: str, svc: PaymentsService = Depends(get_service)):
+        return await svc.get_payment_method(provider_method_id)
+
+    @prot.post(
+        "/methods/{provider_method_id}",
+        response_model=PaymentMethodOut,
+        name="payments_update_method",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Methods"],
+    )
+    async def update_method(
+        provider_method_id: str,
+        data: PaymentMethodUpdateIn,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        out = await svc.update_payment_method(provider_method_id, data)
+        await svc.session.flush()
+        return out
+
+    # ===== Products: get/list/update (archive via active=False) =====
+    @svc.get(
+        "/products/{provider_product_id}",
+        response_model=ProductOut,
+        name="payments_get_product",
+        tags=["Products"],
+    )
+    async def get_product_endpoint(
+        provider_product_id: str, svc: PaymentsService = Depends(get_service)
+    ):
+        return await svc.get_product(provider_product_id)
+
+    @prot.get(
+        "/products",
+        response_model=Paginated[ProductOut],
+        name="payments_list_products",
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Products"],
+    )
+    async def list_products_endpoint(
+        active: Optional[bool] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_products(
+            active=active, limit=ctx.limit, cursor=ctx.cursor
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    @svc.post(
+        "/products/{provider_product_id}",
+        response_model=ProductOut,
+        name="payments_update_product",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Products"],
+    )
+    async def update_product_endpoint(
+        provider_product_id: str,
+        data: ProductUpdateIn,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        out = await svc.update_product(provider_product_id, data)
+        await svc.session.flush()
+        return out
+
+    # ===== Prices: get/list/update (active toggle) =====
+    @prot.get(
+        "/prices/{provider_price_id}",
+        response_model=PriceOut,
+        name="payments_get_price",
+        tags=["Prices"],
+    )
+    async def get_price_endpoint(
+        provider_price_id: str, svc: PaymentsService = Depends(get_service)
+    ):
+        return await svc.get_price(provider_price_id)
+
+    @prot.get(
+        "/prices",
+        response_model=Paginated[PriceOut],
+        name="payments_list_prices",
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Prices"],
+    )
+    async def list_prices_endpoint(
+        provider_product_id: Optional[str] = None,
+        active: Optional[bool] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_prices(
+            provider_product_id=provider_product_id,
+            active=active,
+            limit=ctx.limit,
+            cursor=ctx.cursor,
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    @svc.post(
+        "/prices/{provider_price_id}",
+        response_model=PriceOut,
+        name="payments_update_price",
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Prices"],
+    )
+    async def update_price_endpoint(
+        provider_price_id: str,
+        data: PriceUpdateIn,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        out = await svc.update_price(provider_price_id, data)
+        await svc.session.flush()
+        return out
+
+    # ===== Subscriptions: get/list =====
+    @prot.get(
+        "/subscriptions/{provider_subscription_id}",
+        response_model=SubscriptionOut,
+        name="payments_get_subscription",
+        tags=["Subscriptions"],
+    )
+    async def get_subscription_endpoint(
+        provider_subscription_id: str, svc: PaymentsService = Depends(get_service)
+    ):
+        return await svc.get_subscription(provider_subscription_id)
+
+    @prot.get(
+        "/subscriptions",
+        response_model=Paginated[SubscriptionOut],
+        name="payments_list_subscriptions",
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Subscriptions"],
+    )
+    async def list_subscriptions_endpoint(
+        customer_provider_id: Optional[str] = None,
+        status: Optional[str] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_subscriptions(
+            customer_provider_id=customer_provider_id,
+            status=status,
+            limit=ctx.limit,
+            cursor=ctx.cursor,
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    # ===== Invoices: list line items =====
+    @prot.get(
+        "/invoices/{provider_invoice_id}/lines",
+        response_model=Paginated[InvoiceLineItemOut],
+        name="payments_list_invoice_line_items",
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Invoices"],
+    )
+    async def list_invoice_lines_endpoint(
+        provider_invoice_id: str,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_invoice_line_items(
+            provider_invoice_id, limit=ctx.limit, cursor=ctx.cursor
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    # ===== Refunds: list/get =====
+    @prot.get(
+        "/refunds",
+        response_model=Paginated[RefundOut],
+        name="payments_list_refunds",
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Refunds"],
+    )
+    async def list_refunds_endpoint(
+        provider_payment_intent_id: Optional[str] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_refunds(
+            provider_payment_intent_id=provider_payment_intent_id,
+            limit=ctx.limit,
+            cursor=ctx.cursor,
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    @prot.get(
+        "/refunds/{provider_refund_id}",
+        response_model=RefundOut,
+        name="payments_get_refund",
+        tags=["Refunds"],
+    )
+    async def get_refund_endpoint(
+        provider_refund_id: str, svc: PaymentsService = Depends(get_service)
+    ):
+        return await svc.get_refund(provider_refund_id)
+
+    # ===== Usage Records: list/get =====
+    @prot.get(
+        "/usage_records",
+        response_model=Paginated[UsageRecordOut],
+        name="payments_list_usage_records",
+        dependencies=[Depends(cursor_pager(default_limit=50, max_limit=200))],
+        tags=["Usage Records"],
+    )
+    async def list_usage_records_endpoint(
+        subscription_item: Optional[str] = None,
+        provider_price_id: Optional[str] = None,
+        svc: PaymentsService = Depends(get_service),
+    ):
+        ctx = use_pagination()
+        items, next_cursor = await svc.list_usage_records(
+            UsageRecordListFilter(
+                subscription_item=subscription_item,
+                provider_price_id=provider_price_id,
+                limit=ctx.limit,
+                cursor=ctx.cursor,
+            )
+        )
+        return ctx.wrap(items, next_cursor=next_cursor)
+
+    @prot.get(
+        "/usage_records/{usage_record_id}",
+        response_model=UsageRecordOut,
+        name="payments_get_usage_record",
+        tags=["Usage Records"],
+    )
+    async def get_usage_record_endpoint(
+        usage_record_id: str, svc: PaymentsService = Depends(get_service)
+    ):
+        return await svc.get_usage_record(usage_record_id)
+
+    # --- Canonical: remove local alias/association (non-destructive) ---
+    @prot.delete(
+        "/method_aliases/{alias_id}",
+        name="payments_delete_method_alias",
+        summary="Remove Method Alias (non-destructive)",
+        response_model=PaymentMethodOut,
+        dependencies=[Depends(require_idempotency_key)],
+        tags=["Payment Methods"],
+    )
+    async def delete_method_alias(alias_id: str, svc: PaymentsService = Depends(get_service)):
+        """
+        Removes the local alias/association to a payment method.
+        This does **not** delete the underlying payment method at the provider.
+        Equivalent to `detach_payment_method`.
+        """
+        out = await svc.detach_payment_method(alias_id)
+        await svc.session.flush()
+        return out
+
     routers.append(svc)
     routers.append(pub)
     return routers