Admin Financial Operations Guide

Last Updated: 2025-11-18 Version: 1.0

Overview

This guide covers all financial operations available to admin users including refund processing, price adjustments, payment reconciliation, and financial reporting.

Table of Contents

1. Advanced Refund Management
2. Price Adjustments & Comp Tickets
3. Payment Reconciliation
4. Bulk Financial Operations
5. Financial Reporting
6. Best Practices

---

Advanced Refund Management

Overview

Comprehensive refund processing system for full and partial refunds across multiple payment methods.

Required Permissions

• admin:refunds:view - View refund requests and history
• admin:refunds:process - Process refund requests

API Endpoints

Process Refund:

POST /api/v1/admin/refunds/process

Get Refund Details:

GET /api/v1/admin/refunds/:refundRequestId

Get Booking Refunds:

GET /api/v1/admin/bookings/:bookingId/refunds

Search Refunds:

GET /api/v1/admin/refunds

Processing Full Refunds

Request:

{
  "bookingId": "booking_123",
  "refundType": "full",
  "reason": "Customer requested cancellation due to family emergency",
  "adminNotes": "Customer is regular VIP, approved full refund outside policy window"
}

Response:

{
  "refundRequestId": "refund_req_456",
  "status": "completed",
  "refundAmount": 175.0,
  "feeAmount": 5.25,
  "netRefundAmount": 169.75,
  "paymentBreakdown": [
    {
      "paymentMethod": "stripe",
      "refundedAmount": 120.0,
      "providerRefundId": "re_1ABC123",
      "success": true
    },
    {
      "paymentMethod": "voucher",
      "refundedAmount": 50.0,
      "providerRefundId": "voucher_credit_789",
      "success": true
    }
  ],
  "warnings": []
}

Processing Partial Refunds

Request:

{
  "bookingId": "booking_123",
  "refundType": "partial",
  "amount": 50.0,
  "reason": "Customer arrived 30 minutes late, partial session only",
  "adminNotes": "Prorated refund for 30 minutes of missed session time"
}

Response:

{
  "refundRequestId": "refund_req_789",
  "status": "completed",
  "refundAmount": 50.0,
  "feeAmount": 0.0,
  "netRefundAmount": 50.0,
  "paymentBreakdown": [
    {
      "paymentMethod": "stripe",
      "refundedAmount": 50.0,
      "providerRefundId": "re_1XYZ789",
      "success": true
    }
  ],
  "warnings": []
}

Multi-Payment Method Refunds

The system automatically handles bookings paid with multiple methods:

Example Scenario:

• Total booking: $175
• Paid with:
  • $120 via Stripe
  • $50 via voucher code
  • $5 via loyalty points

Full Refund Distribution:

1. Stripe: $120 refunded to original card (minus fees)
2. Voucher: $50 credited back to customer account
3. Loyalty Points: 500 points restored to account

Partial Refund ($50) Distribution:

• Pro-rated across payment methods
• Typically refunds largest payment source first
• Admin can override distribution if needed

Refund Validation

The system automatically validates:

1. Booking Exists: Booking must exist in tenant
2. Booking Status: Must be paid, completed, part_paid, or confirmed
3. Refund Amount: Cannot exceed remaining refundable amount
4. Concurrent Refunds: Only one refund can process at a time
5. Reason Required: Refund reason must be provided

Bypass Validation:

{
  "bookingId": "booking_123",
  "refundType": "partial",
  "amount": 50.0,
  "reason": "Manager override - special circumstances",
  "skipValidation": true
}

Note: skipValidation requires special permission and should be used sparingly.

Refund Search & Filtering

Search Request:

GET /api/v1/admin/refunds?status=completed&dateFrom=2025-11-01&dateTo=2025-11-30&page=1&limit=50

Available Filters:

Filter	Type	Description
status	string[]	Filter by status (pending, processing, completed, failed, cancelled)
bookingId	string	Specific booking
requestedBy	string	Admin user who requested
dateFrom	ISO date	Start of date range
dateTo	ISO date	End of date range
minAmount	number	Minimum refund amount
maxAmount	number	Maximum refund amount
page	number	Page number
limit	number	Results per page (max 100)
sortBy	string	Sort field (createdAt, amount, status)
sortOrder	string	Sort direction (asc, desc)

Search Response:

{
  "refunds": [
    {
      "refundRequestId": "refund_req_123",
      "bookingId": "booking_456",
      "bookingReference": "booking_456",
      "refundType": "full",
      "amount": 175.0,
      "status": "completed",
      "requestedBy": "admin_sarah",
      "reason": "Customer cancellation",
      "createdAt": "2025-11-18T10:00:00Z",
      "completedAt": "2025-11-18T10:01:30Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 125,
    "totalPages": 3
  },
  "summary": {
    "totalRefunded": 15750.0,
    "pendingAmount": 450.0,
    "completedCount": 120,
    "failedCount": 5
  }
}

Refund Status Tracking

Refund Statuses:

Status	Description	Next Action
pending	Refund created, not yet processed	Processing will begin
processing	Refund in progress with payment provider	Wait for completion
completed	Refund successfully processed	Customer notified
failed	Refund failed (payment issue, etc.)	Review error, retry
cancelled	Refund request cancelled	No further action

Check Refund Status:

GET /api/v1/admin/refunds/:refundRequestId

Response:

{
  "refundRequestId": "refund_req_123",
  "bookingId": "booking_456",
  "bookingReference": "booking_456",
  "refundType": "full",
  "requestedAmount": 175.00,
  "actualRefundAmount": 169.75,
  "feeAmount": 5.25,
  "currency": "EUR",
  "status": "completed",
  "requestedBy": "admin_sarah",
  "requestedByName": "Sarah Johnson",
  "reason": "Customer cancellation",
  "adminNotes": "VIP customer, approved outside policy",
  "paymentBreakdown": [...],
  "providerResponses": [...],
  "createdAt": "2025-11-18T10:00:00Z",
  "processingStartedAt": "2025-11-18T10:00:05Z",
  "completedAt": "2025-11-18T10:01:30Z"
}

Refund Fees

Fee Types:

• Stripe Fees: Non-refundable processing fees (typically 2.9% + $0.30)
• Currency Conversion: If original payment in different currency
• Expedited Processing: If customer requests faster refund
• Chargeback Fees: If refund related to chargeback

Fee Calculation:

Gross Refund Amount:     $175.00
Payment Processing Fee:  -$5.25
Net Refund to Customer:  $169.75

Failed Refund Handling

Common Failure Reasons:

1. Card Expired: Original payment card no longer valid
2. Account Closed: Bank account closed
3. Insufficient Merchant Balance: Merchant account lacks funds
4. Provider Error: Payment provider temporary issue

Resolution Steps:

1. Review Error: Check errorMessage field
2. Contact Customer: Explain situation
3. Alternative Method: Offer refund via different method
4. Manual Processing: Use provider dashboard if needed
5. Document: Add detailed notes to refund request

---

Price Adjustments & Comp Tickets

Overview

Manual price adjustments, discounts, and complimentary tickets for special circumstances.

Required Permission

• admin:pricing:adjust

API Endpoints

Create Price Adjustment:

POST /api/v1/admin/bookings/:bookingId/price-adjustments

Get Adjustment History:

GET /api/v1/admin/bookings/:bookingId/price-adjustments

Search Adjustments:

GET /api/v1/admin/price-adjustments

Creating Price Adjustments

Request:

{
  "adjustmentType": "discount",
  "amount": 25.0,
  "reason": "service_recovery",
  "description": "Compensation for 20-minute wait time",
  "applyAs": "percentage",
  "affectsTotal": true
}

Adjustment Types:

Type	Purpose	Example
discount	Reduce price	Customer service recovery
surcharge	Add to price	Special equipment rental
comp	Free of charge	Promotional giveaway
correction	Fix pricing error	Wrong price applied

Apply As:

• percentage: Apply as percentage (e.g., 20% off)
• fixed_amount: Apply as fixed dollar amount (e.g., $25 off)

Response:

{
  "adjustmentId": "adj_123",
  "bookingId": "booking_456",
  "adjustmentType": "discount",
  "amount": 25.0,
  "previousTotal": 175.0,
  "newTotal": 150.0,
  "reason": "service_recovery",
  "appliedBy": "admin_sarah",
  "appliedAt": "2025-11-18T14:30:00Z"
}

Complimentary Tickets

Full Comp:

{
  "adjustmentType": "comp",
  "amount": 100,
  "applyAs": "percentage",
  "reason": "promotional",
  "description": "Media reviewer - comp admission",
  "affectsTotal": true,
  "waiveAllFees": true
}

Result:

• Booking total: $0.00
• Status: Automatically confirmed
• Payment: Not required
• Notes: Marked as promotional comp

Multi-Item Adjustments

Adjust Specific Items:

{
  "itemAdjustments": [
    {
      "itemType": "base_admission",
      "adjustmentType": "discount",
      "amount": 20,
      "applyAs": "percentage"
    },
    {
      "itemType": "addon",
      "addonId": "addon_pizza",
      "adjustmentType": "comp",
      "amount": 100,
      "applyAs": "percentage"
    }
  ],
  "reason": "vip_package",
  "description": "VIP customer package - 20% off admission, free pizza"
}

Adjustment Approval Workflow

Adjustment Limits by Role:

Role	Max Discount	Max Comp	Approval Required
Front Desk	$25 / 15%	N/A	No
Supervisor	$100 / 30%	Up to $50	No
Manager	$500 / 50%	Up to $200	No
Regional	Unlimited	Unlimited	For >$500

Request Approval:

{
  "adjustmentType": "discount",
  "amount": 200.0,
  "reason": "service_recovery",
  "description": "Major service failure - requires manager approval",
  "requiresApproval": true,
  "approverRole": "manager"
}

Adjustment Audit Trail

All price adjustments are fully audited:

Audit Fields:

• Who made the adjustment
• When it was made
• Original price
• New price
• Reason and description
• Approval information (if applicable)
• Customer notification status

View Audit Trail:

GET /api/v1/admin/bookings/:bookingId/price-adjustments

---

Payment Reconciliation

Overview

Reconciling payments across multiple payment providers and identifying discrepancies.

Required Permission

• admin:payments:reconcile

Daily Reconciliation Workflow

1. Pull payment provider reports
   ↓
2. Export booking system transactions
   ↓
3. Match transactions
   ↓
4. Identify discrepancies
   ↓
5. Investigate and resolve
   ↓
6. Update records
   ↓
7. Generate reconciliation report

API Endpoints

Get Daily Reconciliation:

GET /api/v1/admin/reconciliation/daily/:date

Get Discrepancies:

GET /api/v1/admin/reconciliation/discrepancies

Mark Reconciled:

POST /api/v1/admin/reconciliation/:transactionId/reconcile

Reconciliation Report

Request:

GET /api/v1/admin/reconciliation/daily/2025-11-18

Response:

{
  "date": "2025-11-18",
  "summary": {
    "totalBookings": 45,
    "totalRevenue": 6750.0,
    "stripePayments": 5250.0,
    "paytrailPayments": 1000.0,
    "voucherPayments": 500.0,
    "reconciled": true,
    "discrepancyCount": 2,
    "discrepancyAmount": 15.0
  },
  "providers": [
    {
      "provider": "stripe",
      "expectedAmount": 5250.0,
      "actualAmount": 5240.0,
      "difference": -10.0,
      "reconciled": false,
      "transactionCount": 32
    },
    {
      "provider": "paytrail",
      "expectedAmount": 1000.0,
      "actualAmount": 1000.0,
      "difference": 0.0,
      "reconciled": true,
      "transactionCount": 8
    }
  ],
  "discrepancies": [
    {
      "transactionId": "tx_123",
      "bookingId": "booking_456",
      "expectedAmount": 120.0,
      "actualAmount": 115.0,
      "difference": -5.0,
      "reason": "unknown",
      "requiresInvestigation": true
    }
  ]
}

Common Discrepancies

Discrepancy Type	Common Cause	Resolution
Missing transaction	Failed webhook	Manual import
Amount mismatch	Currency conversion	Verify exchange rate
Duplicate charge	Double submission	Refund duplicate
Partial refund	Not recorded	Update refund record
Fee discrepancy	Fee structure change	Adjust fee calculation

Resolving Discrepancies

Mark as Resolved:

POST /api/v1/admin/reconciliation/discrepancy/:discrepancyId/resolve

Request:

{
  "resolution": "manual_adjustment",
  "notes": "Currency conversion fee not initially accounted for. Fee of $5 is correct.",
  "adjustmentAmount": 5.0,
  "resolvedBy": "admin_sarah"
}

---

Bulk Financial Operations

Overview

Process multiple financial operations simultaneously for efficiency.

Required Permission

• admin:bulk:financial

Bulk Refund Processing

Request:

POST /api/v1/admin/refunds/bulk

Request Body:

{
  "refunds": [
    {
      "bookingId": "booking_123",
      "refundType": "full",
      "reason": "Event cancelled - facility closure"
    },
    {
      "bookingId": "booking_456",
      "refundType": "full",
      "reason": "Event cancelled - facility closure"
    },
    {
      "bookingId": "booking_789",
      "refundType": "full",
      "reason": "Event cancelled - facility closure"
    }
  ],
  "batchReason": "Facility emergency closure - all bookings for 2025-11-20 refunded",
  "notifyCustomers": true
}

Response:

{
  "batchId": "batch_refund_123",
  "totalRequests": 3,
  "successful": 2,
  "failed": 1,
  "totalRefundAmount": 350.0,
  "results": [
    {
      "bookingId": "booking_123",
      "status": "completed",
      "refundRequestId": "refund_req_111",
      "amount": 175.0
    },
    {
      "bookingId": "booking_456",
      "status": "completed",
      "refundRequestId": "refund_req_222",
      "amount": 175.0
    },
    {
      "bookingId": "booking_789",
      "status": "failed",
      "error": "Booking already refunded"
    }
  ]
}

Bulk Price Adjustments

Use Case: Apply discount to all bookings in a date range

Request:

POST /api/v1/admin/price-adjustments/bulk

Request Body:

{
  "filter": {
    "dateFrom": "2025-12-01",
    "dateTo": "2025-12-31",
    "siteId": "site_hq",
    "status": ["confirmed", "paid"]
  },
  "adjustment": {
    "adjustmentType": "discount",
    "amount": 10,
    "applyAs": "percentage",
    "reason": "promotional",
    "description": "Holiday season 10% discount - all December bookings"
  },
  "previewOnly": false,
  "notifyCustomers": true
}

Bulk Payment Status Updates

Request:

POST /api/v1/admin/payments/bulk-update

Request Body:

{
  "bookingIds": ["booking_123", "booking_456", "booking_789"],
  "action": "mark_paid",
  "paymentMethod": "bank_transfer",
  "transactionReference": "WIRE-2025-11-18-001",
  "notes": "Bulk wire transfer received for corporate bookings"
}

---

Financial Reporting

Overview

Comprehensive financial reports for analysis and accounting.

Required Permission

• admin:reports:financial

Available Reports

1. Daily Revenue Report
2. Refund Activity Report
3. Payment Method Distribution
4. Price Adjustment Summary
5. Outstanding Payments Report
6. Reconciliation Report

Daily Revenue Report

Request:

GET /api/v1/admin/reports/revenue/daily?date=2025-11-18

Response:

{
  "date": "2025-11-18",
  "revenue": {
    "grossRevenue": 7500.0,
    "refunds": -250.0,
    "adjustments": -125.0,
    "netRevenue": 7125.0
  },
  "breakdown": {
    "admissions": 6000.0,
    "addons": 1200.0,
    "merchandise": 300.0
  },
  "paymentMethods": {
    "stripe": 5500.0,
    "paytrail": 1500.0,
    "voucher": 500.0
  },
  "bookingStats": {
    "totalBookings": 52,
    "averageValue": 144.23,
    "cancelledBookings": 3,
    "noShows": 1
  }
}

Refund Activity Report

Request:

GET /api/v1/admin/reports/refunds?dateFrom=2025-11-01&dateTo=2025-11-30

Response:

{
  "period": {
    "from": "2025-11-01",
    "to": "2025-11-30"
  },
  "summary": {
    "totalRefunds": 42,
    "totalAmount": 5250.0,
    "averageRefund": 125.0,
    "fullRefunds": 30,
    "partialRefunds": 12
  },
  "byReason": [
    {
      "reason": "customer_request",
      "count": 25,
      "amount": 3125.0
    },
    {
      "reason": "service_issue",
      "count": 10,
      "amount": 1250.0
    },
    {
      "reason": "weather",
      "count": 7,
      "amount": 875.0
    }
  ],
  "trend": [
    {
      "date": "2025-11-01",
      "count": 2,
      "amount": 250.0
    }
  ]
}

Export Options

Export to CSV:

GET /api/v1/admin/reports/revenue/export?format=csv&dateFrom=2025-11-01&dateTo=2025-11-30

Export to Excel:

GET /api/v1/admin/reports/revenue/export?format=xlsx&dateFrom=2025-11-01&dateTo=2025-11-30

Export to PDF:

GET /api/v1/admin/reports/revenue/export?format=pdf&dateFrom=2025-11-01&dateTo=2025-11-30

---

Best Practices

Refund Processing

1. Document Everything: Always include detailed reason and notes
2. Verify First: Check booking status and payment history
3. Process Promptly: Complete refunds within 24 hours
4. Communicate: Keep customer informed of refund status
5. Audit Trail: Review refund history regularly

Price Adjustments

1. Justify: Document clear business reason
2. Get Approval: Follow approval workflow for large amounts
3. Be Consistent: Apply similar adjustments for similar situations
4. Track Impact: Monitor adjustment trends
5. Limit Access: Restrict adjustment permissions appropriately

Reconciliation

1. Daily Reconciliation: Don't let discrepancies accumulate
2. Investigate Promptly: Resolve discrepancies within 48 hours
3. Document Resolutions: Keep clear records of how issues resolved
4. Automate: Use automated reconciliation where possible
5. Review Patterns: Look for systemic issues

Reporting

1. Regular Review: Generate reports on consistent schedule
2. Trend Analysis: Compare periods to identify patterns
3. Share Insights: Distribute reports to relevant stakeholders
4. Act on Data: Use reports to drive operational improvements
5. Archive: Maintain historical reports for compliance

---

Related Documentation

• Booking Management Guide
• Customer Service Guide
• Operations Guide
• API Reference - Payments