Skip to main content

Admin Features & Reporting

This document describes the administrative features for managing donations, viewing reports, and monitoring the donation platform.

Admin Interface (Avo)​

The application uses Avo admin framework for managing donation-related records.

Accessing Admin Panel​

  • URL: https://reports.aleteia.org/avo (production)
  • Authentication: Requires authenticated admin user
  • Authorization: Role-based permissions via Pundit policies

Admin Resources​

Donors (Donations::Donor)​

Resource Controller: app/controllers/avo/donations_donors_controller.rb

Fields Displayed:

  • ID
  • Email (with mailto link)
  • First Name
  • Last Name
  • Country
  • Stripe Customer ID (with link to Stripe Dashboard)
  • PayPal Payer ID
  • Created At
  • Updated At

Actions:

  • View donor details
  • Edit donor information
  • View donor's transactions
  • View donor's subscriptions
  • View donor's notifications

Filters:

  • Payment method (Stripe/PayPal)
  • Country
  • Date range

Transactions (Donations::Transaction)​

Resource Controller: app/controllers/avo/donations_transactions_controller.rb

Fields Displayed:

  • ID
  • Amount (formatted with currency)
  • Currency
  • Payment Date
  • Transaction ID (Stripe charge/subscription ID)
  • Campaign (if associated)
  • Donor (link to donor record)
  • Recurring flag
  • Created At

Actions:

  • View transaction details
  • Export transactions to CSV
  • View associated notification
  • View in Stripe Dashboard (link)

Filters:

  • Date range (payment date)
  • Currency
  • Campaign
  • Recurring vs one-time
  • Amount range

Sorting:

  • By payment date (default: descending)
  • By amount
  • By donor

Subscriptions (Donations::Subscription)​

Resource Controller: app/controllers/avo/donations_subscriptions_controller.rb

Fields Displayed:

  • ID
  • Subscription ID (Stripe subscription ID)
  • Donor (link to donor)
  • Started At
  • Ended At (null if active)
  • Recurring flag
  • Status (active/canceled)
  • Plan Description

Actions:

  • View subscription details
  • Cancel subscription (if active)
  • View in Stripe Dashboard (link)
  • View associated transactions

Filters:

  • Status (active/canceled)
  • Payment processor (Stripe/PayPal)
  • Date range (started at)

Scopes:

  • Active subscriptions
  • Canceled subscriptions
  • Stripe subscriptions
  • PayPal subscriptions

Notifications (Donations::Notification)​

Resource Controller: app/controllers/avo/donations_notifications_controller.rb

Fields Displayed:

  • ID
  • Event Type (txn_type)
  • Donor
  • Subscription (if applicable)
  • Created At
  • Raw Data (JSON viewer)

Actions:

  • View notification details
  • View event in Stripe Dashboard
  • Replay event (reprocess webhook)

Filters:

  • Event type
  • Date range
  • Payment processor (Stripe/PayPal)
  • Has transaction

Scopes:

  • Stripe events
  • PayPal events
  • Successful charges
  • Failed charges
  • Subscription events

Campaigns (Donations::Campaign)​

Fields Displayed:

  • ID
  • Name
  • Target (amount in default currency)
  • Total Raised (calculated)
  • Progress Percentage
  • Created At

Actions:

  • Create campaign
  • Edit campaign
  • View campaign transactions
  • View campaign statistics

Reports & Analytics​

Transaction Reports​

Daily Payments Report​

Generated via background job and emailed to staff.

Job: Donations::PaymentsReportJob

Scheduling: Daily via Sidekiq Cron at 9 AM

Report Content:

  • Total donations for yesterday
  • Number of transactions
  • Breakdown by currency
  • Single vs recurring split
  • Top campaigns
  • Failed payments count

Email Recipients: Configured in settings

Monthly Summary​

Transaction totals can be queried by date range and campaign for monthly summaries.

Campaign-Specific Reports​

Campaign-specific totals can be retrieved filtered by campaign name and date range.

Statistics Methods​

The application provides methods for calculating:

  • Grand Totals: Multi-currency totals grouped by currency
  • Total Amount: Single currency totals with automatic conversion
  • Campaign Statistics: Progress toward campaign goals including target, current total, and progress percentage

API Endpoints for Reports​

GET /donations/campaign_data​

Returns campaign information by name.

Response:

{
  "id": 1,
  "name": "Spring2018",
  "target_cents": 10000000,
  "target_currency": "EUR",
  "created_at": "2018-03-01T00:00:00.000Z",
  "updated_at": "2018-03-01T00:00:00.000Z"
}

Used by frontend to display campaign progress bars.

Donation Wall​

Real-time display of recent donations on the donations website, showing:

  • Donor name (first name only)
  • Donation amount
  • Time since donation
  • Badge for recurring donations

Background Jobs for Reporting​

The application uses several background jobs for generating reports:

1. Payments Report Job​

Generates and emails daily donation summary including:

  • Total donations for the day
  • Number of transactions
  • Breakdown by currency
  • Single vs recurring split
  • Top campaigns
  • Failed payments count

2. Abandoned Sessions Report​

Tracks payment intents that were created but not completed, helping identify potential issues in the checkout flow.

3. Update Conversion Rates​

Updates currency exchange rates daily to ensure accurate reporting across multiple currencies.

Slack Notifications​

Real-time donation notifications sent to configured Slack channel.

Configuration​

  • Slack webhook URL configured via settings
  • Channel name configurable (e.g., "#donations")
  • Username displayed as 'donations.aleteia.org'

Message Format​

Messages include:

  • Donor name and email
  • Donation amount
  • Payment type (single or recurring)
  • Campaign name (if applicable)
  • Appropriate emoji and color coding

Example notification:

donations.aleteia.org [9:45 AM]
💰 John Smith ([email protected]) just donated €50.00 (recurring) to Aleteia

Amount: €50.00 | Type: Recurring
Campaign: Spring2018

Failed PayPal payments​

A subscr_failed IPN means PayPal could not collect a recurring donation. PayPal informs the payer and retries on its own (the IPN carries the retry_at date), so the application only records the notification on the donor and the subscription and posts it on Slack with the retry date.

Data Export​

CSV Export​

Admin can export transaction data to CSV format including:

  • Transaction ID and date
  • Donor email
  • Amount and currency
  • Payment type (recurring/single)
  • Campaign name
  • Stripe transaction ID

JSON Export​

API endpoint available for programmatic access to donation data with filtering options by date range, campaign, and currency.

Monitoring & Alerts​

Key Metrics to Monitor​

  1. Transaction Volume:

    • Daily/weekly/monthly totals
    • Comparison to historical averages
    • Alert if significant drop

  2. Success Rate:

    • Percentage of successful vs failed payments
    • Track failure reasons
    • Alert if rate drops below threshold

  3. Webhook Processing:

    • Webhook event count
    • Processing latency
    • Failed job count
    • Alert on repeated failures

  4. Subscription Churn:

    • Cancellation rate
    • Failed recurring payment rate
    • Alert on spike in cancellations

  5. Fraud Indicators:

    • Multiple failed attempts
    • Unusual geographic patterns
    • High-value single donations

Dashboard Recommendations​

Metrics to Display:

  • Total raised (all time)
  • Monthly recurring revenue (MRR)
  • Active subscriptions count
  • Average donation amount
  • Top campaigns
  • Recent donations (wall)
  • Geographic distribution
  • Payment method breakdown
  • Currency breakdown

Charts:

  • Donations over time (line chart)
  • Daily donation volume (bar chart)
  • Campaign progress (progress bars)
  • Payment methods (pie chart)
  • Currency distribution (pie chart)

Best Practices​

Data Management​

  1. Regular Backups: Daily database backups of donation data
  2. Data Retention: Keep all transaction records indefinitely (legal/tax requirements)
  3. PII Protection: Encrypt donor personal information
  4. Access Control: Limit admin access to authorized staff only

Reporting​

  1. Regular Schedule: Daily and monthly automated reports
  2. Alert Thresholds: Configure alerts for unusual activity
  3. Data Validation: Cross-check reports with Stripe Dashboard
  4. Export Regularly: Backup data exports to external storage

Compliance​

  1. GDPR: Provide donor data export and deletion capabilities
  2. PCI DSS: Never store raw card data (handled by Stripe)
  3. Tax Records: Maintain records for required period (7+ years)
  4. Audit Trail: Log all admin actions on donation records

Next Steps​