Admin Operations

Role & Responsibilities

Admin users are SalesArck internal staff. They have cross-tenant visibility and the ability to perform privileged operations that merchants and consumers cannot.

Capability	Admin	Merchant	Consumer
View any tenant	✅	✅ own only	❌
View any wallet	✅	✅ own tenant	✅ own only
Manual wallet adjustment	✅	❌	❌
Freeze / suspend account	✅	❌	❌
View audit logs	✅	❌	❌
Manage reward rules (override)	✅	✅ own tenant	❌
Revoke POS connection	✅	✅ own	❌

---

Fraud Intervention Flow

---

Wallet Adjustment

Admins can credit or debit any wallet with a required reason and audit trail. This is the only way to directly modify a balance outside normal transaction processing.

POST /api/v1/admin/wallets/:walletId/adjustments
Authorization: Bearer <admin-token>

{
  "amount": -500,
  "reason": "Fraud reversal — case #2025-1112",
  "adminId": "admin_01HZ..."
}

Response:

{
  "adjustment": {
    "id": "adj_01HZ...",
    "walletId": "wallet_xyz",
    "amount": -500,
    "newBalance": 750,
    "reason": "Fraud reversal — case #2025-1112",
    "adminId": "admin_01HZ...",
    "createdAt": "2025-11-14T10:30:00Z"
  }
}

Every adjustment creates an immutable audit_logs entry. These cannot be deleted.

---

Audit Logs

All privileged actions emit an audit log entry:

Action	Logged Fields
WALLET_FREEZE	walletId, adminId, reason, timestamp
WALLET_UNFREEZE	walletId, adminId, reason, timestamp
WALLET_ADJUSTMENT	walletId, amount, reason, adminId, newBalance, timestamp
TENANT_SUSPEND	tenantId, adminId, reason, timestamp
USER_SUSPEND	userId, adminId, reason, timestamp
RULE_OVERRIDE	tenantId, ruleId, adminId, oldValue, newValue, timestamp

Audit logs are:

• Write-once (no UPDATE or DELETE on audit_logs table)
• Accessible only to admin role
• Exported for compliance review on request

---

Tenant Management

Admins can view, enable, or suspend tenants:

GET  /admin/tenants              — paginated tenant list with status, connection state
GET  /admin/tenants/:id          — single tenant with POS connections, rule count, wallet count
POST /admin/tenants/:id/suspend  — suspend all activity for tenant {reason}
POST /admin/tenants/:id/resume   — un-suspend tenant

Suspending a tenant:

• Marks all incoming webhooks from that tenant as quarantined (no points issued)
• Does not delete any data
• Merchant sees banner in portal: "Account suspended — contact support"

---

Consumer Lookup

Find any consumer by phone number or wallet ID:

GET /admin/consumers?phone=+14155551234
GET /admin/consumers/:consumerId
GET /admin/consumers/:consumerId/wallets
GET /admin/wallets/:walletId/ledger

---

Alerts Dashboard

The admin console shows active alerts in priority order:

Type	Trigger
VELOCITY_REDEMPTION	> 10 redemptions from one wallet in < 1 hour
LARGE_ADJUSTMENT	Manual adjustment > 10,000 points
POS_DISCONNECT	POS token refresh failed 3× — merchant needs to reconnect
RECONCILIATION_MISMATCH	Wallet balance ≠ ledger sum for any wallet
WEBHOOK_DLQ	Webhook moved to dead-letter queue

Alerts can be acknowledged (snoozed 24h) or resolved (closed with a note).