{
  "version": "local-2026-09-15",
  "source_of_truth": [
    "shortpay/app.py",
    "shortpay/commerce_api.py",
    "shortpay/directory_management.py",
    "shortpay/admin_auth.py",
    "shortpay/stripe_api.py",
    "shortpay/hosted.py"
  ],
  "excluded": [
    {
      "path": "/static/*",
      "methods": [
        "MOUNT"
      ],
      "reason": "Static admin, checkout, and brand assets; not an API contract."
    }
  ],
  "routes": [
    {
      "method": "GET",
      "path": "/",
      "visibility": "public",
      "auth": "none",
      "summary": "Minimal ShortPay homepage; links only to the protected admin entry."
    },
    {
      "method": "GET",
      "path": "/docs",
      "visibility": "public",
      "auth": "none",
      "summary": "Public developer documentation site backed by reviewed static documents."
    },
    {
      "method": "GET",
      "path": "/admin",
      "visibility": "public shell",
      "auth": "login required for data",
      "summary": "Admin application shell; API data uses Cookie session after sign-in."
    },
    {
      "method": "GET",
      "path": "/healthz",
      "visibility": "public",
      "auth": "none",
      "summary": "Process liveness."
    },
    {
      "method": "GET",
      "path": "/readyz",
      "visibility": "public",
      "auth": "none",
      "summary": "Database readiness."
    },
    {
      "method": "POST",
      "path": "/admin/auth/login",
      "visibility": "admin",
      "auth": "configured key + exact Origin",
      "summary": "Creates revocable HttpOnly admin Cookie session."
    },
    {
      "method": "GET",
      "path": "/admin/auth/session",
      "visibility": "admin",
      "auth": "admin Cookie",
      "summary": "Returns current browser session metadata and CSRF token."
    },
    {
      "method": "POST",
      "path": "/admin/auth/logout",
      "visibility": "admin",
      "auth": "admin Cookie + Origin + CSRF",
      "summary": "Revokes session and clears Cookie."
    },
    {
      "method": "GET",
      "path": "/v1/docs",
      "visibility": "public documentation",
      "auth": "none",
      "summary": "Reviewed Markdown, JSON catalog, or integration skill selected only from a static allowlist; no secrets."
    },
    {
      "method": "GET",
      "path": "/v1/merchants",
      "visibility": "authenticated",
      "auth": "Bearer scoped key or limited admin Cookie",
      "summary": "Authorized merchant directory."
    },
    {
      "method": "POST",
      "path": "/v1/merchants",
      "visibility": "admin",
      "auth": "platform Bearer or Cookie + CSRF",
      "summary": "Creates merchant directory record."
    },
    {
      "method": "GET",
      "path": "/v1/sites",
      "visibility": "authenticated",
      "auth": "Bearer scoped key or limited admin Cookie",
      "summary": "Authorized site directory and shared channel status."
    },
    {
      "method": "POST",
      "path": "/v1/sites",
      "visibility": "admin",
      "auth": "platform Bearer or Cookie + CSRF",
      "summary": "Creates a site and generates credentials."
    },
    {
      "method": "POST",
      "path": "/v1/sites/{site_id}/credentials",
      "visibility": "sensitive admin",
      "auth": "platform/merchant Bearer or Cookie + CSRF",
      "summary": "Explicitly reveals site API key and webhook secret."
    },
    {
      "method": "POST",
      "path": "/management/customers",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Creates or resolves a site customer."
    },
    {
      "method": "GET",
      "path": "/management/customers",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Looks up customer by required external_customer_id."
    },
    {
      "method": "GET",
      "path": "/management/customers/{customer_id}",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Reads one authorized customer."
    },
    {
      "method": "PATCH",
      "path": "/management/customers/{customer_id}",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Updates customer email and/or billing address."
    },
    {
      "method": "POST",
      "path": "/management/checkout-sessions",
      "visibility": "private management",
      "auth": "Bearer scoped key + Idempotency-Key",
      "summary": "Creates/replays one payment checkout session."
    },
    {
      "method": "GET",
      "path": "/management/checkout-sessions/{session_id}",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Reads one checkout session and snapshot associations."
    },
    {
      "method": "POST",
      "path": "/management/checkout-sessions/{session_id}/access",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Renews a checkout capability after merchant verifies order ownership."
    },
    {
      "method": "POST",
      "path": "/management/checkout-sessions/{session_id}/embedded",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Creates/replays embedded provider paySession; browser must not call it."
    },
    {
      "method": "GET",
      "path": "/management/payments",
      "visibility": "private management",
      "auth": "Bearer scoped key or limited admin Cookie",
      "summary": "Lists authorized payments with offset pagination."
    },
    {
      "method": "GET",
      "path": "/management/payments/{payment_id}",
      "visibility": "private management",
      "auth": "Bearer scoped key or limited admin Cookie",
      "summary": "Reads one authorized payment."
    },
    {
      "method": "POST",
      "path": "/management/payments/{payment_id}/reconcile",
      "visibility": "private management",
      "auth": "Bearer scoped key or limited admin Cookie + CSRF",
      "summary": "Queries original provider payment; finality is configuration-gated."
    },
    {
      "method": "GET",
      "path": "/management/payments/{payment_id}/refunds",
      "visibility": "private management",
      "auth": "Bearer scoped key or limited admin Cookie",
      "summary": "Lists refunds for a payment."
    },
    {
      "method": "POST",
      "path": "/management/refunds",
      "visibility": "private management",
      "auth": "Bearer scoped key or limited admin Cookie + CSRF + Idempotency-Key",
      "summary": "Creates/replays a refund request; explicit approval required."
    },
    {
      "method": "GET",
      "path": "/management/refunds/{refund_id}",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Reads one authorized refund."
    },
    {
      "method": "POST",
      "path": "/management/refunds/{refund_id}/reconcile",
      "visibility": "private management",
      "auth": "Bearer scoped key or limited admin Cookie + CSRF",
      "summary": "Queries original provider refund; finality is configuration-gated."
    },
    {
      "method": "GET",
      "path": "/management/invoices/{invoice_id}",
      "visibility": "private management",
      "auth": "Bearer scoped key or limited admin Cookie",
      "summary": "Reads paid invoice metadata/body."
    },
    {
      "method": "GET",
      "path": "/management/invoices/{invoice_id}/html",
      "visibility": "private management",
      "auth": "Bearer scoped key or limited admin Cookie",
      "summary": "Returns sandboxed invoice HTML."
    },
    {
      "method": "GET",
      "path": "/management/invoices/{invoice_id}/pdf",
      "visibility": "private management",
      "auth": "Bearer scoped key or limited admin Cookie",
      "summary": "Returns PDF or 202 with Retry-After while pending."
    },
    {
      "method": "GET",
      "path": "/management/events/{event_id}",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Reads known event ID; no event list endpoint."
    },
    {
      "method": "GET",
      "path": "/management/events/{event_id}/delivery",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Reads worker delivery state."
    },
    {
      "method": "POST",
      "path": "/management/events/{event_id}/retry",
      "visibility": "private management",
      "auth": "Bearer scoped key",
      "summary": "Requeues undelivered event only."
    },
    {
      "method": "GET",
      "path": "/checkout/{session_id}",
      "visibility": "capability",
      "auth": "checkout token query",
      "summary": "Hosted checkout view with configured iframe origins."
    },
    {
      "method": "GET",
      "path": "/checkout-api/{session_id}",
      "visibility": "capability",
      "auth": "checkout token query",
      "summary": "Safe checkout display object."
    },
    {
      "method": "POST",
      "path": "/checkout-api/{session_id}/pay",
      "visibility": "payment write",
      "auth": "checkout token query",
      "summary": "Starts exactly one configured provider attempt."
    },
    {
      "method": "GET",
      "path": "/checkout-api/{session_id}/qr",
      "visibility": "capability",
      "auth": "checkout token query",
      "summary": "Locally generated QR SVG when action is qrcode."
    },
    {
      "method": "GET",
      "path": "/embed.js",
      "visibility": "public",
      "auth": "none",
      "summary": "Browser checkout modal helper."
    },
    {
      "method": "POST",
      "path": "/webhooks/sunrate/payment",
      "visibility": "provider callback",
      "auth": "Sunrate signed body",
      "summary": "Verifies and records provider purchase callback; responds plain OK."
    },
    {
      "method": "POST",
      "path": "/webhooks/sunrate/refund",
      "visibility": "provider callback",
      "auth": "Sunrate signed body",
      "summary": "Verifies and records provider refund callback; responds plain OK."
    },
    {
      "method": "POST",
      "path": "/v1/customers",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Create customer; pinned 2025-03-31.basil subset."
    },
    {
      "method": "POST",
      "path": "/v1/customers/{customer_id}",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Update customer; pinned 2025-03-31.basil subset."
    },
    {
      "method": "GET",
      "path": "/v1/customers/{customer_id}",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Retrieve customer; pinned 2025-03-31.basil subset."
    },
    {
      "method": "POST",
      "path": "/v1/checkout/sessions",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Create session; pinned 2025-03-31.basil subset."
    },
    {
      "method": "GET",
      "path": "/v1/checkout/sessions/{session_id}",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Retrieve session; pinned 2025-03-31.basil subset."
    },
    {
      "method": "GET",
      "path": "/v1/checkout/sessions/{session_id}/line_items",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Line items; pinned 2025-03-31.basil subset."
    },
    {
      "method": "POST",
      "path": "/v1/checkout/sessions/{session_id}/expire",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Expire session; pinned 2025-03-31.basil subset."
    },
    {
      "method": "GET",
      "path": "/v1/payment_intents/{intent_id}",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Retrieve intent; pinned 2025-03-31.basil subset."
    },
    {
      "method": "POST",
      "path": "/v1/refunds",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Create refund; pinned 2025-03-31.basil subset."
    },
    {
      "method": "GET",
      "path": "/v1/refunds/{refund_id}",
      "visibility": "public Stripe subset",
      "auth": "single-site Bearer key",
      "summary": "Retrieve refund; pinned 2025-03-31.basil subset."
    },
    {
      "method": "POST",
      "path": "/checkout-api/{session_id}/prepare",
      "auth": "Session capability token",
      "visibility": "hosted checkout",
      "summary": "Atomically freeze local buyer snapshot and reserve one card attempt; return paySession for SDK Mode 1."
    },
    {
      "method": "POST",
      "path": "/checkout-api/{session_id}/pay-card",
      "visibility": "checkout",
      "auth": "session capability and exact same-origin Origin",
      "summary": "Reserve one Direct Card attempt and buyer snapshot; return allowlisted status and trusted authentication redirect."
    },
    {
      "method": "GET",
      "path": "/v1/account",
      "visibility": "public business",
      "auth": "Site Bearer",
      "summary": "Stable site account identity; settlement capability flags unknown."
    },
    {
      "method": "GET",
      "path": "/v1/charges",
      "visibility": "public business",
      "auth": "Site Bearer",
      "summary": "Confirmed payment charges with verified paid time, created filters and bidirectional cursor pagination."
    },
    {
      "method": "GET",
      "path": "/v1/events",
      "visibility": "public business",
      "auth": "Site Bearer",
      "summary": "Immutable charge.succeeded revenue snapshots with created filters and bidirectional cursor pagination; no webhook delivery."
    },
    {
      "method": "GET",
      "path": "/terms",
      "visibility": "public",
      "auth": "none",
      "summary": "Public terms of service HTML page."
    },
    {
      "method": "GET",
      "path": "/privacy",
      "visibility": "public",
      "auth": "none",
      "summary": "Public privacy policy HTML page."
    }
  ]
}