Payments Management

What it is

A unified payments management system that tracks and manages all workspace payments across different payment types (AI Tools, SMS, Storage, Subscription) in a single interface. The system automatically records payments from subscription renewals and allows administrators to manually add payments for offline transactions.

Who it's for

Admin

Access & Scope

Property	Value
Module	payments
Personas	admin
Scope	Platform-level
UI Location	Admin Dashboard > Payments
Status	active

UI Location

Admin Dashboard > Payments

How it works

The Payments Management system provides a centralized view of all workspace payments with comprehensive filtering, statistics, and management capabilities.

Payment Types

The system tracks four types of payments:

1. AI Tools Payments: Payments for AI tool usage and credits
2. SMS Payments: Payments for SMS message credits
3. Storage Payments: Payments for additional storage capacity
4. Subscription Payments: Payments for workspace subscription renewals

Payment Methods

Payments can be made using:

• Cash: Physical cash payments
• Bank Transfer: Bank wire transfers
• Card: Credit/debit card payments
• Other: Other payment methods

Automatic vs Manual Payments

Automatic Payments

• Created automatically by the system
• Cannot be edited or deleted
• Examples:
  • Subscription renewals (when workspace renews subscription)
  • System-generated payment records

Manual Payments

• Added by administrators
• Can be edited and deleted
• Used for:
  • Offline payments (cash, bank transfer)
  • Payments processed outside the system
  • Recording historical payments

Features

1. Payment List View

• View all payments in a unified table
• Sortable columns (date, amount, type, workspace)
• Pagination support (10, 25, 50, 100 items per page)
• Real-time data updates

2. Advanced Filtering

• Period Filter:
  • Daily: Payments from today
  • Weekly: Payments from current week
  • Monthly: Payments from current month
  • Custom Range: Select start and end dates
• Payment Type Filter: Filter by AI Tools, SMS, Storage, or Subscription
• Workspace Filter: Searchable dropdown to filter by specific workspace
• Date Range: Custom date range selection with calendar picker

3. Payment Statistics

Statistics cards display:

• Total Payments: All-time total amount and count
• This Month: Current month's total amount and count
• This Week: Current week's total amount and count
• Today: Today's total amount and count

Statistics update automatically based on applied filters.

4. Add Manual Payment

• Select workspace (with searchable dropdown)
• Choose payment type
• Enter amount and payment method
• Set payment date
• Add description and notes
• Upload receipt image (optional)

5. Edit/Delete Manual Payments

• Edit payment details (amount, method, date, description, notes)
• Delete payments (with confirmation)
• Only manual payments can be edited/deleted

6. Searchable Workspace Dropdown

• Real-time search by workspace name or email
• Debounced search (300ms) for performance
• Displays workspace name and email
• Click-outside to close

Automatic Payment Recording

The system automatically creates payment records for:

Subscription Renewals

• Trigger: When workspace renews subscription
• Location: Client subscription renewal page
• Details Recorded:
  • Payment amount (calculated from plan price)
  • Applied discount (if workspace has discount)
  • Payment method (card or other for WhatsApp)
  • Plan information in metadata
• Status: Automatic payment (isManual: false)

SMS Payments

• Trigger: When admin adds SMS payment via SMS tracking page
• Details Recorded:
  • Payment amount
  • Payment method
  • Receipt image (if provided)
  • Linked to original SMS payment record
• Status: Manual payment (isManual: true)

AI Tools Payments

• Trigger: When admin adds AI tools payment via AI tracking page
• Details Recorded:
  • Payment amount
  • Payment method
  • Receipt image (if provided)
  • Linked to original AI payment record
• Status: Manual payment (isManual: true)

Payment Data Structure

Each payment record includes:

• Basic Information: ID, workspace, type, amount, method, date
• Descriptive Fields: Description, notes
• Receipt: Receipt image (URL, path, dimensions, size)
• Metadata: Type-specific additional data
• Tracking: Created by (for manual payments), timestamps

Use Cases

1. Revenue Tracking: Monitor total revenue from all payment types
2. Workspace Billing: Track payments per workspace
3. Payment Reconciliation: Match offline payments with system records
4. Financial Reporting: Generate reports by date range, type, or workspace
5. Audit Trail: Maintain complete payment history

API Integration

The Payments Management system is fully integrated with the admin API:

• List Payments: GET /api/v1/admin/payments
• Get Statistics: GET /api/v1/admin/payments/stats
• Create Payment: POST /api/v1/admin/payments
• Update Payment: PATCH /api/v1/admin/payments/:paymentId
• Delete Payment: DELETE /api/v1/admin/payments/:paymentId

See API Documentation for detailed endpoint documentation.

Permissions

• View Payments: Requires payments.view permission
• Manage Payments: Requires payments.manage permission (for create/update/delete)

Best Practices

1. Add Receipts: Always upload receipt images for manual payments when available
2. Accurate Dates: Ensure payment dates match actual transaction dates
3. Descriptive Notes: Add notes for context (e.g., "Payment received via bank transfer, reference #12345")
4. Regular Reconciliation: Periodically review and reconcile payments
5. Filter Usage: Use filters to focus on specific time periods or workspaces

Future Enhancements

Potential improvements:

• Export payments to CSV/Excel
• Payment reports and analytics
• Recurring payment management
• Payment reminders
• Integration with accounting systems
• Payment reconciliation tools
• Automated payment matching