Management Portal

1. Overview

The Management Portal is the internal admin surface for platform staff and support operators. It manages organizations as the top-level tenant, locations as the canonical child records, and keeps a smaller set of location-scoped sub-pages for day-to-day operations and support follow-through. It uses Firebase Authentication with SAML SSO for enterprise identity provider integration.

Terminology note: the current gateway data model is Organization -> Location. Some management endpoints and older UI copy still use legacy merchant naming as a compatibility alias. When this page references /api/v1/merchants/* or merchantAccess, read that as the concrete location-scoped surface unless called out otherwise.

Closeout note: for docs and launch communication, the preferred story is now organization/location-first. Legacy merchant route and claim names remain here only where they still match the shipped wire contract or claim shape.

2. Authentication Architecture

Firebase Auth + SAML SSO

┌──────────────┐     ┌────────────────┐     ┌──────────────────┐
│   User       │     │  Firebase      │     │  Enterprise      │
│   Browser    │     │  Auth          │     │  IdP (SAML)      │
└──────┬───────┘     └───────┬────────┘     └────────┬─────────┘
       │                     │                       │
       │ 1. Click "SSO Login"│                       │
       │────────────────────>│                       │
       │                     │                       │
       │                     │ 2. SAML AuthnRequest  │
       │                     │──────────────────────>│
       │                     │                       │
       │                     │ 3. User authenticates │
       │                     │    at IdP             │
       │                     │                       │
       │                     │ 4. SAML Response      │
       │                     │<──────────────────────│
       │                     │                       │
       │ 5. Firebase ID Token│                       │
       │<────────────────────│                       │
       │                     │                       │
       │ 6. Use token to call│                       │
       │    Management API   │                       │

Auth Methods Supported

Method	Use Case
SAML SSO	Primary, enterprise customers with their own IdP (Okta, Azure AD, Google Workspace)
Email/Password	Fallback, small merchants without an IdP
MFA (TOTP)	Required for admin-level roles

Firebase Configuration

// Firebase Auth SAML provider configuration
const samlProvider = new SAMLAuthProvider('saml.pinpoint-gateway');

// Provider config (set via Firebase Admin SDK)
{
  providerId: 'saml.pinpoint-gateway',
  idpEntityId: '<customer-idp-entity-id>',
  ssoURL: '<customer-sso-url>',
  x509Certificates: ['<customer-cert>'],
  rpEntityId: 'pinpoint-gateway-portal',
  callbackURL: 'https://portal.pinpointgateway.com/__/auth/handler'
}

Role-Based Access Control (RBAC)

Role	Permissions
super_admin	All operations. Manage SAML providers. System configuration.
admin	Manage organizations/locations, users, view all reports. Cannot configure SAML.
merchant_admin	Legacy role label for a user who manages assigned organization/location settings, users, and reports.
merchant_user	Legacy role label for a user who can view assigned organization/location reports and process manual transactions.
readonly	View-only access to assigned location data.

Roles are stored as Firebase Custom Claims and validated server-side by the Management Microservice.

The role names merchant_admin and merchant_user are still present in the claim shape, but they should be read as compatibility labels for organization/location-scoped access, not as a preferred merchant-first model.

2.1 Rename guardrails

Safe statements:

• the portal manages organizations and locations as the primary tenant model
• legacy merchantAccess and /api/v1/merchants/* references are compatibility surfaces
• older UI copy may still say "merchant" where the runtime contract has not yet been renamed

Unsafe statements:

• that merchantAccess represents a different scope model from location access
• that new portal UX or docs should keep introducing fresh merchant-first terminology
• that all route names and claims are already fully renamed

3. Portal Features

3.1 Dashboard

• Transaction volume summary (today, this week, this month)
• Revenue summary
• Decline rate and top decline reasons
• Recent transaction list
• System health status

3.2 Organization and Location Management

Feature	Description
Create location	Board a new location and attach it to the correct organization
Edit location	Update location settings, MID/TID, contact info
Suspend/activate	Toggle location processing capability
View location	Full location profile with transaction history
List locations	Paginated, searchable location directory (legacy /merchants API alias still exists)

3.2.1 Organization cutover workflow

The current admin-facing closeout path for the organization/location rename is:

1. Open Organizations and drill into the target organization.
2. Use the cutover checklist on organization detail to confirm:
   • a default credential profile is selected
   • at least one credential profile is active
   • pending approvals are cleared
   • at least one active location exists
   • any remaining legacy merchant aliases are known support exceptions
3. Use the organization-detail Operator Shortcuts to jump into:
   • Event Log with organizationId prefilled
   • Gift Cards with organizationId prefilled
   • Tax Configs with organizationId prefilled
4. Only treat the org as rename-closeable when the checklist is green and the supporting admin surfaces no longer depend on merchant-only interpretation.

What is promised:

• organization detail is the canonical admin handoff surface for rename cleanup
• Event Log, Gift Cards, and Tax Configs can now be opened in organization- scoped mode directly from organization detail
• legacy merchant aliases are treated as support and migration artifacts, not as the preferred tenant model

What is not promised:

• that every API route name is already renamed away from /merchants
• that legacy claims such as merchantAccess have disappeared from the wire
• that every downstream service has fully removed merchant-shaped compatibility aliases

3.3 Transaction Management

Feature	Description
Transaction search	By date range, amount, card last 4, status, location
Transaction detail	Full transaction lifecycle (auth → capture → settle)
Manual void	Void an uncaptured authorization
Manual refund	Process a return/refund on a settled transaction
Manual keyed entry	Process a manually keyed sale (virtual terminal equivalent)
Export	CSV/PDF export of transaction reports

3.4 Settlement & Reporting

Feature	Description
Daily settlement report	Batch totals, transaction counts, net amounts
Reconciliation status	Match our records vs TransIT settlement
Monthly statement	Per-location monthly processing summary
Custom reports	Date range, location, card type filters

3.5 User Management

Feature	Description
Create user	Invite user via email, assign role
Edit user	Change role, assigned organizations/locations
Disable/enable	Toggle user access
Audit log	User login history, actions performed

3.6 SAML SSO Configuration (super_admin only)

Feature	Description
Add SAML provider	Configure new IdP (entity ID, SSO URL, certificate)
Test SAML connection	Validate IdP configuration
Edit SAML provider	Update IdP settings
Remove SAML provider	Decommission an IdP connection

4. Technical Stack

Layer	Technology
Framework	React 19 + Vite
Language	TypeScript
Styling	Tailwind CSS
Components	shadcn/ui
Auth	Firebase Auth SDK (Web v9+)
Auth UI	@firebase-oss/ui-react
State	React hooks + page-local async loaders
Charts	Recharts on analytics/reporting pages
Tables	Repo-local table primitives
Forms	React Hook Form + Zod validation
Routing	hash-based route state inside the SPA shell
Build	Vite + TypeScript (Bazel-compatible workspace build)
Testing	Vitest + Playwright (E2E)

5. API Integration

The portal communicates exclusively with the Management Microservice REST API.

Key Endpoints Consumed

GET    /api/v1/organizations                # List organizations
GET    /api/v1/organizations/{id}           # Organization detail
GET    /api/v1/organizations/{id}/locations # Organization child locations
GET    /api/v1/organizations/{id}/credential-profiles
POST   /api/v1/organizations/{id}/credential-profiles/{profileId}/approve
POST   /api/v1/organizations/{id}/credential-profiles/{profileId}/reject

GET    /api/v1/merchants                    # List locations (legacy route alias)
POST   /api/v1/merchants                    # Create location (legacy route alias)
GET    /api/v1/merchants/{id}               # Get location (legacy route alias)
PUT    /api/v1/merchants/{id}               # Update location (legacy route alias)
PATCH  /api/v1/merchants/{id}/status        # Suspend/activate location

GET    /api/v1/webhook-events               # Org-scoped event log browser
GET    /api/v1/webhook-events/{id}          # Event detail
GET    /api/v1/webhook-events/{id}/deliveries

GET    /v1/organizations/{orgId}/gift-cards
GET    /v1/organizations/{orgId}/gift-cards/liability
GET    /v1/organizations/{orgId}/tax-configs

GET    /api/v1/transactions                 # Search transactions
GET    /api/v1/transactions/{id}            # Get transaction detail
POST   /api/v1/transactions/{id}/void       # Void transaction
POST   /api/v1/transactions/{id}/refund     # Refund transaction
POST   /api/v1/transactions/manual          # Manual keyed entry

GET    /api/v1/settlements                  # List settlement batches
GET    /api/v1/settlements/{id}             # Settlement detail

GET    /api/v1/reports/daily                # Daily report
GET    /api/v1/reports/monthly              # Monthly report
GET    /api/v1/reports/custom               # Custom date range

GET    /api/v1/users                        # List users
POST   /api/v1/users                        # Create user
PUT    /api/v1/users/{id}                   # Update user
DELETE /api/v1/users/{id}                   # Disable user

GET    /api/v1/audit-log                    # Audit trail

Auth Header

Authorization: Bearer <firebase-id-token>

The Management Microservice validates the Firebase ID token, extracts custom claims (role and legacy merchantAccess / merchantIds location-targeting fields), derives permissions server-side, and enforces RBAC.

5.2 Operator deep-link behavior

Organization detail now deep-links to several admin surfaces with hash-query prefill:

• #/event-log?organizationId=org_xxx
• #/gift-cards?organizationId=org_xxx
• #/tax-configs?organizationId=org_xxx

These links are intentionally portal-local convenience flows. They do not imply that every backend endpoint is query-string driven; they are an admin UX layer for carrying organization context through rename cleanup and support triage.

5.1 Docs-side closeout checklist

Treat the portal docs as repo-closeable for the rename when this page makes all of the following explicit:

• organization/location is the preferred product and UX model
• merchantAccess / merchantIds are legacy location-targeting compatibility claims
• /api/v1/merchants/* examples are read as current wire compatibility, not as the desired long-term naming
• support and launch communication can repeat this page without implying a separate merchant-first tenant model still exists

6. Deployment

• Hosting: Firebase Hosting (CDN-backed static hosting) or Cloud Run (SSR)
• Domain: portal.pinpointgateway.com (TBD)
• TLS: Managed by Firebase Hosting / Cloud Load Balancer
• Build artifact: Static export or Docker container (depending on SSR needs)