Admin endpoints

These endpoints are intended for the gateway operator’s dashboard (ZPCC), not for products. Authentication is a single bearer token (ADMIN_TOKEN env on the gateway), not per-app HMAC.

GET /admin/<endpoint>
Authorization: Bearer <ADMIN_TOKEN>

Mode filtering

/admin/summary, /admin/payments, /admin/refunds, and /admin/timeseries accept an optional ?mode=test|sandbox|live query param. Empty/absent = no filter (returns all modes). Unknown values silently demote to no filter; the response echoes back the resolved mode so the dashboard can detect typos.

GET /admin/summary?days=30&mode=sandbox

/admin/balances does not yet honor ?mode= — balance fetching is bound to PSP credentials, and the gateway wires one fetcher per PSP (preferring live). Mode segmentation for balances is a separate piece of work.

Endpoints

`GET /admin/summary?days=N&since=...&mode=...`

Aggregated payment + refund totals grouped by app / provider / currency.

{
  "since":       "2026-04-09T...",
  "as_of":       "2026-05-09T...",
  "mode":        "sandbox",
  "by_app":      [ { "app_id": "...", "app_name": "quay-sandbox", "app_mode": "sandbox", "succeeded_count": 5, "succeeded_minor": 7500, "refunded_minor": 0, "net_minor": 7500, ... } ],
  "by_provider": [ { "provider": "polar", "succeeded_count": 3, ... } ],
  "by_currency": [ { "currency": "USD", "succeeded_count": 3, ... } ]
}

`GET /admin/payments?mode=...`

Most-recent N payments (default 100) with refund status attached. Use ?mode= to scope.

{ "payments": [ { "id": "...", "mode": "sandbox", "status": "succeeded", ... } ] }

`GET /admin/refunds?mode=...`

Most-recent refunds.

{ "refunds": [ { "id": "...", "mode": "sandbox", "amount_minor": 1500, ... } ] }

`GET /admin/timeseries?days=N&mode=...`

Daily per-currency succeeded sums for the last N days.

{
  "days": 30,
  "mode": "sandbox",
  "buckets": [
    { "day": "2026-05-09", "currency": "USD", "succeeded_count": 1, "succeeded_minor": 100 }
  ]
}

`GET /admin/balances`

Live + calculated balances per PSP. PayPal pulls real balances via Transaction Search; other PSPs return calculated succeeded - refunded from gateway DB.

{
  "balances": [
    { "provider": "paypal", "source": "real", "currency": "USD", "available_minor": 12345, "as_of": "..." },
    { "provider": "polar",  "source": "calculated", "currency": "USD", "available_minor": 7500 }
  ]
}

`GET /admin/payouts?since=&until=`

Payout history per PSP. PayPal pulls real payouts; others return source: "api_unavailable".

Other admin actions

GET /admin/apps, POST /admin/apps, POST /admin/apps/{id}/regenerate-keys
POST /admin/payments/{id}/cancel — admin-initiated cancel (intelligently routes to refund if already succeeded)
POST /admin/payments/{id}/refund
POST /admin/payments/{id}/retry-webhook — re-enqueue an outbound delivery if the product’s endpoint was down

These are not exposed to product apps. Each is documented in the gateway source under internal/httpx/handlers/admin.go.