Topolo Pay

Public overview of the payment worker that handles orders, refunds, and payment operations.

publicverified 2026-07-29paymentsordersworker

What It Is

Topolo Pay is the payment-processing worker that powers order creation, refunds, admin payment operations, and related operational flows.

Architecture

The system is a worker-first payment surface with admin routes, webhook handling, and payment API operations. Inbound webhook verification remains domain-local. Outbound Stripe order creation, refunds, payment-status reads, and cancellation operations now route through Nexus.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

See /systems/topolo-pay for the runtime inventory and deployment entrypoints.

API Reference

Use /systems/topolo-pay plus the internal handbook for the current worker route inventory and the local-webhook versus Nexus-outbound payment boundary.

Auth and Permissions

Topolo Pay uses Topolo Auth and the shared platform middleware for admin permission checks on operational routes. Its outbound Nexus payment calls use trusted service credentials plus fixed attribution to the Auth organization with slug topolo. Pay app identity is resolved from the Auth-owned topolo-pay service slug at runtime; browser bundles must not embed production or staging app_* ids. Protected admin bearer-token authorization validates with Auth and does not accept locally decoded JWT claims from a Pay Worker secret. Admin browser login handoff and SSO callbacks delegate to the shared Topolo Auth client, including Auth /sso/exchange handling, so callback URLs carry one-time sso_code values rather than bearer tokens. Pay now also normalizes any missing Auth role claim to member before its local admin compatibility layer evaluates access.

Data Ownership

Topolo Pay owns order, transaction, refund, and payment-operation records. Nexus owns centralized external-service credential usage for supported outbound provider calls.

Mobile Experience

The checked-in mobile experience contract is approved in native_capability mode. Its fallback route is /transactions, its offline policy is read_through_cache, and it requires organization context.

Published permissions: transactions:read, customers:read, merchants:read.

  • /transactions uses /api/admin/transactions with the record.list template and pay.transactions.list data source.
  • /transactions/:id uses /api/admin/transaction/:id with the record.detail template and pay.transactions.detail data source.
  • /customers uses /api/admin/customers with the record.list template and pay.customers.list data source.
  • /merchants uses /api/merchants with the record.list template and pay.merchants.list data source.
  • /merchants/:id uses /api/admin/merchants/:id with the record.detail template and pay.merchants.detail data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Topolo Pay deploys as a Cloudflare worker with admin and webhook surfaces. Standardized outbound payment routes require NEXUS_SERVICE_TOKEN and NEXUS_ORGANIZATION_ID; local webhook verification still uses STRIPE_WEBHOOK_SECRET. The isolated staging worker is published in the separate Topolo Staging Cloudflare account at https://pay.stg.topolo.us. Its staging build injects staging Auth and Pay origins, and the worker requires explicit Auth, Nexus, and Pay app URL bindings instead of falling back to production hosts. Pay stamps platform security headers, including HSTS, content-type sniffing protection, referrer policy, frame protection, cross-origin opener policy, and a restrictive permissions policy, on worker responses in both staging and production.

Failure Modes

  • order, refund, status, or cancellation routes drift from the current Nexus payment standard
  • webhook verification and outbound payment calls are confused as the same integration boundary
  • worker responses lose the shared platform security-header baseline

Debugging

Start with /systems/topolo-pay and distinguish inbound webhook verification from outbound payment API calls before debugging provider issues.

Use It

Open Topolo Pay for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-pay --json
topolo actions --service topolo-pay --json
topolo actions capabilities --service topolo-pay --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Topolo Pay and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Verified the native_capability mobile experience contract and its 5 published route(s) against apps/TopoloPay origin/staging a8540c0d8627 on 2026-07-27.

  • Reconciled this page against apps/TopoloPay origin/staging efcd323ba3d9 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloPay commits through a8c2813; reviewed 174 commits since 2026-06-03, including a8c2813 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); b7e1c68 Adopt canonical Topolo typography; f2fd1fa Split Pay startup bundle; 7734bdd Remove Pay Topolo vendor monolith.

  • Added Pay worker security headers on 2026-05-14 and verified the staging pentest header failure no longer applies.

  • Verified Pay app identity centralization on 2026-05-13 so the worker and admin shell resolve the environment app id from Auth by slug and the rebuilt admin bundle carries no hardcoded app ids.

  • Recorded the isolated Topolo Staging Pay worker target on 2026-04-29.

  • Verified Pay staging URL isolation on 2026-04-30 so the staging admin bundle and worker runtime resolve Auth, Pay, and Nexus through staging configuration.

  • Removed Pay's residual Worker JWT_SECRET handoff on 2026-04-18 so protected admin bearer-token authorization validates through Auth instead of local JWT claims.

  • Corrected Pay role normalization on 2026-04-24 so missing Auth role claims resolve to member before the admin compatibility layer runs.

  • Delegated Pay admin login handoff and callback-code redemption to the shared Topolo Auth client on 2026-04-18.

  • Removed the remaining legacy Pay auth compatibility surface on 2026-04-11 so the live worker now resolves admin auth only through Topolo Auth naming and the shared middleware path

  • Promoted Pay admin browser SSO callbacks to Auth /sso/exchange on 2026-04-17 so callback URLs carry a one-time sso_code instead of bearer tokens

  • Restored the live Pay admin shell fallback for /dashboard on 2026-04-07 so direct app links and suite handoff keep loading the React admin frontend instead of the worker JSON 404

  • Replaced the Pay admin launcher with the shared Topolo app switcher on 2026-04-07 so the live operator UI now uses the current suite icon set and standard cross-app launcher behavior instead of the older local overlay

  • Verified the Nexus-backed Topolo Pay outbound payment boundary on 2026-03-30