Automatic Refunds

The automatic refund system detects rides that likely failed or malfunctioned and automatically refunds customers to their wallet. This helps maintain customer satisfaction when vehicles malfunction, fail to unlock properly, or have other issues that result in very short, unsuccessful rides.

How It Works

The Automatic Refund Flow

When a ride ends, the system evaluates whether it qualifies for an automatic refund:

Why the Delay?

The system waits a configurable number of minutes before processing the refund. This delay allows:

1. Late-arriving telemetry data to update ride metrics
2. IoT data sync to complete with final distance/duration
3. Backend processing to finalize ride calculations

This prevents premature refunds based on incomplete data.

Eligibility Criteria

A ride qualifies for automatic refund when ALL of the following are true:

What Gets Checked

The eligibility evaluation uses the following ride data:

• Duration in seconds
• Distance in meters
• Total cost
• Amount charged
• Payment status

Configuration

Accessing Settings

Configure automatic refunds in the admin dashboard:

1. Navigate to Settings
2. Click the Rides tab
3. Find the Automatic Refunds section

Configuration Options

Recommended Values by Use Case

Conservative (Fewer Refunds)

Use these settings if you want to minimize automatic refunds and prefer manual review:

Standard (Balanced)

The default settings balance customer satisfaction with operational oversight:

Generous (More Refunds)

Use these settings for maximum customer satisfaction:

Job Statuses

Automatic refund jobs progress through these statuses:

Cron Job Details

The automatic refunds cron runs every 5 minutes via Vercel Cron.

Processing Behavior

Each cron execution:

1. Processes up to 25 jobs per run
2. Only processes jobs where scheduled_for ≤ NOW()
3. Uses optimistic locking to prevent double-processing
4. Cleans up expired jobs older than 7 days

Response Format

The cron endpoint returns processing statistics:

{
  "success": true,
  "timestamp": "2025-01-19T12:00:00Z",
  "duration_ms": 1234,
  "processed": 15,
  "succeeded": 12,
  "cancelled": 2,
  "failed": 1,
  "total_refunded_usd": 24.50
}

Admin Dashboard

Access the automatic refunds dashboard at Dashboard > Refunds > Automatic.

Dashboard Features

Statistics Cards

• Pending Jobs - Number of jobs waiting to be processed
• Succeeded (24h) - Successful refunds in the last 24 hours
• Total Refunded (24h) - Dollar amount refunded
• Success Rate - Percentage of jobs that succeeded

Pending Jobs Table

• Ride link
• Customer link
• Ride metrics (duration, distance)
• Refund amount
• Scheduled processing time
• Cancel action

Failed Jobs Alert

• Prominently displayed when jobs need attention
• Retry and cancel actions

Recent Refunds Table

• Processed refunds from last 24 hours
• Amount, customer, ride details
• Job ID for troubleshooting

Available Actions

Refund Process Details

What Happens During Refund

1. Job Lock Acquired - Status set to processing
2. Settings Validated - Check if auto-refund still enabled
3. Ride Re-fetched - Get latest ride metrics
4. Eligibility Re-evaluated - Confirm still within thresholds
5. Refundable Amount Calculated - Actual paid minus already refunded
6. Wallet Credited - Customer's wallet balance increased
7. Wallet Transaction Created - Audit trail recorded
8. Ride Updated - Marked as refunded if fully refunded
9. Notification Sent - Push notification to customer
10. Job Completed - Status set to succeeded

Customer Notification

When an automatic refund is issued, customers receive:

Push Notification:

• Title: "Ride refund issued"
• Body: "A recent ride was automatically refunded to your wallet."

Wallet Transaction:

• Type: Credit
• Description: "Automatic ride refund"
• Reference: Ride UUID

Cancellation Reasons

Jobs may be cancelled for various reasons:

Manual Refunds

In addition to automatic refunds, operators can manually issue refunds through the dashboard.

Refund Types

Refund Modes

Processing a Manual Refund

Permission Requirements

Refunds require the ride:refund permission. The following roles can process refunds:

• super_admin
• global_admin
• admin
• general_manager
• franchisee_manager
• fleet_manager
• customer_support

Note: Analysts and service technicians cannot process refunds.

Monitoring

View Pending Jobs

SELECT
  id,
  ride_uuid,
  customer_uuid,
  status,
  scheduled_for,
  attempts,
  created_at
FROM ride_auto_refund_jobs
WHERE status = 'pending'
ORDER BY scheduled_for ASC;

View Recent Automatic Refunds

SELECT
  r.id,
  r.ride_uuid,
  r.customer_uuid,
  r.amount,
  r.processed_at,
  r.metadata->>'job_id' as job_id
FROM ride_refunds r
WHERE r.metadata->>'automatic_refund' = 'true'
  AND r.processed_at > NOW() - INTERVAL '24 hours'
ORDER BY r.processed_at DESC;

Check Failed Jobs

SELECT
  id,
  ride_uuid,
  customer_uuid,
  attempts,
  last_error,
  created_at
FROM ride_auto_refund_jobs
WHERE status = 'failed'
ORDER BY updated_at DESC
LIMIT 20;

Troubleshooting

Jobs Not Being Created

Check 1: Is automatic refund enabled?

• Navigate to Settings > Rides > Automatic Refunds
• Verify the toggle is on

Check 2: Are ride metrics within thresholds?

• Check ride duration (must be ≤ max_ride_duration_minutes)
• Check ride distance (must be ≤ max_total_distance_m)

Check 3: Does ride have a customer?

• Verify the ride is linked to a valid customer

Jobs Stuck in Pending

Check 1: Is the cron running?

• Verify Vercel cron is configured
• Check Vercel dashboard for cron execution logs

Check 2: Are jobs scheduled in the future?

• Jobs won't process until scheduled_for ≤ NOW()

Check 3: Check Vercel function logs for errors

Jobs Failing

Common errors and solutions:

Performance Tuning

High-Volume Fleets

For fleets with many rides, consider:

1. Increasing cron frequency - Run every 2-3 minutes instead of 5
2. Increasing batch size - Process 50-100 jobs per run
3. Monitoring queue backlog - Set up alerts for pending job count

Database Optimization

Ensure these indexes exist for optimal performance:

-- Pending job lookup
CREATE INDEX CONCURRENTLY IF NOT EXISTS
  idx_ride_auto_refund_jobs_pending_scheduled
  ON ride_auto_refund_jobs (scheduled_for)
  WHERE status = 'pending';

-- Customer wallet lookup
CREATE INDEX CONCURRENTLY IF NOT EXISTS
  idx_customers_wallet
  ON customers (id, wallet_balance);

Recommended Alerts

Set up alerts for:

1. High Failure Rate - Alert when failed jobs > 10% of processed
2. Queue Backlog - Alert when pending jobs > 100
3. Processing Delay - Alert when jobs are overdue by > 30 minutes
4. Execution Errors - Alert when cron endpoint returns 500

What's Next?

• Stripe Setup - Configure Stripe integration
• Payment Methods - Managing customer cards
• Damage Charges - Charging customers for damage