application public active Verified 2026-04-29

Topolo Pay

Payment worker handling orders, webhooks, admin APIs, and static-asset-backed application behavior.

Documentation Map

What It Is

Payment worker handling orders, webhooks, admin APIs, and static-asset-backed application behavior.

Canonical documentation for Topolo Pay lives in `PlatformApplications/TopoloDocs`.

Use this directory for implementation only. Payment boundaries, deployment guidance, auth, and external-service integration rules are canonical in the docs application and should not be duplicated here.

Architecture

Owners: commerce

Source repos: PlatformApplications/TopoloPay

Dependencies: topolo-auth, topolo-nexus, topolo-p2p, applications-packages

Repo shape

  • PlatformApplications/TopoloPay/README.md
  • PlatformApplications/TopoloPay/admin/
  • PlatformApplications/TopoloPay/dist-admin/
  • PlatformApplications/TopoloPay/migration.config.ts
  • PlatformApplications/TopoloPay/package-lock.json
  • PlatformApplications/TopoloPay/package.json
  • PlatformApplications/TopoloPay/public/
  • PlatformApplications/TopoloPay/schema.sql
  • PlatformApplications/TopoloPay/src/
  • PlatformApplications/TopoloPay/test/
  • PlatformApplications/TopoloPay/topolo.cloudcontrol.json
  • PlatformApplications/TopoloPay/tsconfig.json
  • PlatformApplications/TopoloPay/vitest.config.mts
  • PlatformApplications/TopoloPay/worker-configuration.d.ts
  • PlatformApplications/TopoloPay/wrangler.jsonc

Runtime Surfaces

Hosts:

https://pay.topolo.app https://topolo-pay.topolo.workers.dev https://topolo-pay-staging.topolo-staging.workers.dev

No wrangler surface was discovered under the registered repo paths.

API Reference

Coverage: curated

Source: PlatformApplications/TopoloDocs/src/content/public/applications/pay.mdx

Source exists in repo: yes

Canonical public and internal docs cover the payment worker, local webhook boundary, Nexus-routed outbound payment operations, the authenticated `GET /api/widget` live-workspace endpoint for TopoloOne, code-exchange-only admin SSO with in-memory access-token handling, and the worker-owned `/login` redirect that must run before the SPA fallback. TopoloPay is also the only Stripe-mutating service for TopoloP2P settlement batches; P2P submits typed settlement requests to Pay and receives Pay status callbacks.

App API page: /reference/apps/topolo-pay

This system currently relies on a curated or README-derived contract surface instead of a source-controlled OpenAPI spec.

Auth and Permissions

Depends on Topolo Auth: yes

Service IDs:

srv_DJInUxp0dLLi

API key scopes

analytics.read

View payment analytics

Resource pattern: none

audit.read

View payment audit logs

Resource pattern: none

customers.read

View customer payment profiles

Resource pattern: none

customers.write

Manage customer payment methods

Resource pattern: none

dashboard.read

View TopoloPay dashboards and operational summaries

Resource pattern: none

invoices.read

View invoices and billing

Resource pattern: none

invoices.write

Create and manage invoices

Resource pattern: none

payments.create

Create payment or checkout sessions

Resource pattern: none

payments.read

Read payment and charge state

Resource pattern: none

reports.read

View payment reports and analytics

Resource pattern: none

settings.read

View payment gateway settings

Resource pattern: none

settings.write

Configure payment processing

Resource pattern: none

settlements.write

Accept TopoloP2P settlement batches

Resource pattern: none

transactions.read

View payment transactions

Resource pattern: none

transactions.refund

Refund transactions

Resource pattern: none

transactions.write

Process payments and refunds

Resource pattern: none

venues.read

View venue configuration

Resource pattern: none

venues.write

Manage venue configuration

Resource pattern: none

Service permissions

analytics:read, audit:read, customers:read, customers:write, dashboard:read, invoices:read, invoices:write, payments:create, payments:read, reports:read, settings:read, settings:write, settlements:write, transactions:read, transactions:refund, transactions:write, venues:read, venues:write

Data Ownership

No storage bindings were derived from wrangler configuration.

Queues / Cron / Workflows

Queue bindings:

No queue bindings were detected.

Cron triggers

No cron triggers were detected.

Workflow signals

No explicit queue/workflow script or cron signal was discovered.

Environment Variables and Bindings

Environment variables:

No environment variables were derived from wrangler configuration.

All wrangler bindings

No bindings were derived from wrangler configuration.

Deployments

Deployment environments: default only or not declared

Routes: workers.dev or Pages-only delivery

Observability enabled: no explicit setting found

Build and deploy commands

  • build — PlatformApplications/TopoloPay/admin/package.json :: tsc -b && vite build
  • preview — PlatformApplications/TopoloPay/admin/package.json :: vite preview
  • deploy — PlatformApplications/TopoloPay/package.json :: npm run build:admin && wrangler deploy
  • deploy:staging — PlatformApplications/TopoloPay/package.json :: npm run build:admin:staging && env -u CLOUDFLARE_API_TOKEN CLOUDFLARE_ACCOUNT_ID=4f4e1c69a3830946f9fea7b1eb7531ac wrangler deploy --env staging
  • build — PlatformApplications/TopoloPay/package.json :: npm run build:admin
  • deploy:dry-run — PlatformApplications/TopoloPay/package.json :: npm run build:admin && wrangler deploy --dry-run --outdir .wrangler/build
  • deploy:dry-run:staging — PlatformApplications/TopoloPay/package.json :: npm run build:admin:staging && env -u CLOUDFLARE_API_TOKEN CLOUDFLARE_ACCOUNT_ID=4f4e1c69a3830946f9fea7b1eb7531ac wrangler deploy --env staging --dry-run --outdir .wrangler/build-staging
  • build:admin — PlatformApplications/TopoloPay/package.json :: cd admin && npm install && env VITE_AUTH_URL=https://auth.topolo.app VITE_PAY_APP_URL=https://pay.topolo.app npm run build
  • build:admin:staging — PlatformApplications/TopoloPay/package.json :: cd admin && npm install && env VITE_AUTH_URL=https://auth.stg.topolo.us VITE_PAY_APP_URL=https://topolo-pay-staging.topolo-staging.workers.dev npm run build

Failure Modes

  • No wrangler.toml surface was discovered under the registered repo paths.

Debugging Runbooks

Start with these entrypoints:

  • PlatformApplications/TopoloDocs/src/content/public/applications/pay.mdx
  • PlatformApplications/TopoloPay/README.md
  • PlatformApplications/TopoloPay/admin/package.json
  • PlatformApplications/TopoloPay/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-04-29

Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.