Admin portal architecture and functional specification

This document details the architecture, access control, screen workflows, and audit controls for payofy-admin, the internal console used by Spicyfy staff to manage merchants, observe transaction movements, and handle cross-tenant operations.

Overview

payofy-admin is served at admin.payofy.si and admin.payofy.com. The console provides internal tooling for Spicyfy staff. Merchants, schools, and end customers do not access this application. They interface with embedded elements or the merchant portal.

The application communicates exclusively with /admin/v1 endpoints on payofy-api using an authenticated staff JSON Web Token (JWT). It never interacts with the downstream processor (Kurv) directly.

Users and role permissions

Access control is enforced on the server for every incoming request. The console defines five distinct staff roles:

• Owner: Holds full system privileges. Can manage staff users, generate and revoke API keys, edit webhook endpoints, alter fee schedules, issue refunds, adjust merchant states, and view unmasked data.
• Operations: Focuses on onboarding and daily operations. Manages merchant applications, details, refunds, voids, and webhook or job replays. Cannot modify fee schedules, API keys, or staff users.
• Risk: Focuses on risk mitigation and underwriting compliance. Can suspend or restrict merchants, inspect and respond to disputes, and issue refunds or voids. Cannot alter fee schedules or API keys.
• Finance: Manages money movements, fees, and reconciliation. Can edit fee schedules, review daily matches, resolve exceptions, and post adjusting ledger entries. Cannot issue refunds or suspend merchants.
• Read-only: Audit and read-only inspection access across every screen. All personally identifiable information (PII) is masked by default.

Role permission matrix

Action	Owner	Operations	Risk	Finance	Read-only
View every screen (PII masked)	Yes	Yes	Yes	Yes	Yes
Manage applications, edit details	Yes	Yes	No	No	No
Change fee schedules	Yes	No	No	Yes	No
Refund and void payments	Yes	Yes	Yes	No	No
Suspend or restrict a merchant	Yes	No	Yes	No	No
Respond to disputes	Yes	Yes	Yes	No	No
Resolve reconciliation, post adjustments	Yes	No	No	Yes	No
Create or revoke API keys, webhooks	Yes	No	No	No	No
Replay webhooks, retry queue jobs	Yes	Yes	No	No	No
Reveal unmasked PII	Yes	Yes	Yes	No	No
Manage staff users and settings	Yes	No	No	No	No

Screen structure

The application layout organizes 15 screens across five navigation groups:

1. Overview

• Home: Displays today's gross volume, platform take, and active count tiles for pending applications, open disputes, failed jobs, reconciliation exceptions, and webhook delivery errors. Clicking any tile opens the corresponding screen with pre-applied filters.
• Top bar search: Global search input capable of resolving merchants, DBA names, merchant identification numbers (MIDs), payment identifiers, Kurv transaction identifiers, customer emails, and card last four digits plus amount.

2. Merchants

• Merchants: Merchant directory filterable by tenant, status (draft, submitted, approved, active, restricted, suspended, closed), MCC code, and creation date. Supports viewing business details, masked owner data, fee schedule updates with effective dates, and restrict/suspend actions with mandatory reasons.
• Applications: Underwriting queue categorized by stage (draft, submitted, documents requested, approved, declined). Shows days in current stage, uploaded document verification status, Kurv underwriting sync, and information request dispatch.

3. Money

• Payments: Complete register of charges, refunds, voids, and ACH returns. Detail modal displays gross amount, processing fees, Spicyfy platform margin, ledger postings, processor response codes, and card vault status. Provides refund and void controls requiring a compliance reason.
• Subscriptions and past due: Recurring subscription status, billing run monitor, and past-due dunning queue with manual retry, dunning pause, and external payment settlement options.
• Disputes: Chargeback items sorted by response deadline. Facilitates uploading evidence packages, submitting formal responses to Kurv, and logging outcomes.
• Reconciliation and payouts: Daily transaction matching results, unmatched volume difference alerts, and exceptions queue. Authorizes Finance staff to post audited adjusting ledger entries. Lists merchant payout settlement batches with destination bank details.
• Revenue: Expected Spicyfy net margin per merchant and billing month calculated from active fee schedules. Supports Kurv residual statement imports, variance analysis, and CSV export.

4. Platform

• Tenants and keys: Directory of platform tenants (Budofy, Voiceyfy). Manages live and test API keys with one-time secret reveals, key rotation, immediate revocation, and webhook endpoints with HMAC signing secrets and test event pings.
• Webhooks and jobs: Inbound processor event log with signature validation status and event replay. Outbound tenant webhook deliveries with response codes and resend options. BullMQ dead-letter queue with job retry and discard controls.
• Partners (Phase 2): ISV partner directory, Know Your Business (KYB) verification status, basis-point revenue share terms, monthly statements, and onboarding capacity caps.

5. Admin

• Audit log: Immutable, append-only security log recording every staff and API-key action, actor, role, affected resource, details/reason, client IP address, and timestamp. Complies with PCI DSS 10.5.1 with 3-month instant search and 12-month archive filtering and CSV export.
• Settings: Default fee schedule templates mapped by tenant and MCC code, automated dunning retry policies with terminal exhaustion states, and email/SMS notification previews.
• Staff: Staff user roster. Permits the Owner to invite new staff through Google Workspace SSO, adjust role assignments across the five tiers, and deactivate access.

Security and compliance standards

1. Authentication: Google Workspace Single Sign-On (SSO) with mandatory Multi-Factor Authentication (MFA). No passwords or private keys are stored in the Payofy database.
2. PII masking: Beneficial owner tax identifiers (SSN/EIN), dates of birth, and home addresses remain masked with asterisks by default. Staff with permission (Owner, Operations, Risk) can unmask records; every unmask action is recorded in the audit log.
3. Cardholder data: Full payment card numbers and bank account numbers are never received or held by Payofy. The console displays card brand, last four digits, expiry, and vault token reference only.
4. Mandatory audit trail: Every state-altering action (status updates, fee changes, key revocations, ledger adjustments, dispute responses) requires an explicit rationale and is committed to the audit ledger in the same database transaction.
5. No alert popups: Application messaging relies strictly on accessible toast notifications and dedicated confirmation modals. Native browser alerts are prohibited.