public active Last verified 2026-04-29

Topolo Pay

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

Owners
commerce
Source Repos
PlatformApplications/TopoloPay
Systems
Topolo Auth, Topolo Nexus, Topolo Pay
Tags
payments, orders, worker

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.

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. 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.

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://topolo-pay-staging.topolo-staging.workers.dev until pay.stg.topolo.us DNS is delegated there.

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

Debugging

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

Change Log / Verification

  • Recorded the isolated Topolo Staging Pay worker target on 2026-04-29.
  • 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