Inkress ADRsarchitecture decisions
Overview / KYC / verify
ADR 0001

Merchant-facing `/verify` links use the risk-dashboard host

AcceptedKYC / verify

Context

We are adding an API that lets integrators mint a KYC /verify link for a merchant they own (see docs/superpowers/specs/2026-07-28-integrator-kyc-verify-links-design.md). The link must point at a host that serves the merchant-facing capture flow (/verify?token=…).

Today that flow is served by the commerce-risk dashboard app — the same deployment that also hosts the operator/auditor console — on its existing public, chromeless /verify, /upload, and /login routes (dashboard/app/root.tsx). A cleaner separation would be a dedicated merchant-facing verify domain, distinct from the operator console host.

Decision

Reuse the existing risk-dashboard host for merchant /verify links for now. The verify link host is a single configuration value in commerce-api:

COMMERCE_RISK_VERIFY_BASE_URL   # e.g. https://<risk-dashboard-host>

verify_url = "#{COMMERCE_RISK_VERIFY_BASE_URL}/verify?token=<opaque>".

Rationale: the dashboard's /verify route was purpose-built to serve this flow, so it works today with no new infrastructure. The merchant-facing routes are already public and chromeless, so a merchant landing there does not see the operator console. Standing up a separate domain is deferred until there is a reason to (branding, stricter host isolation, or CSP separation).

Consequences

  • Positive: ships now, no new host/deploy/DNS/cert; one config value; easy to change later.
  • Neutral / to revisit: the merchant-facing capture flow and the operator console share a host and deployment. Acceptable because the /verify path is public-by-design and the operator console is auth-gated, but it does mean host-level isolation between "merchant input" and "operator review" is weaker than a split-domain setup.
  • Reversible: because the host is a single config value (COMMERCE_RISK_VERIFY_BASE_URL), moving to a dedicated verify domain later is a config + DNS change, not a code change.

Revisit when

  • We want merchant-facing branding on the verify flow, or
  • Security review calls for host/CSP isolation between the capture flow and the operator console, or
  • The verify flow needs to scale or deploy independently of the console.
0002 Discounts are server-authoritative and modeled as a fee group →