Auto Top-Up Configuration

Auto top-up automatically replenishes customer wallet balances when they fall below a configurable threshold. This ensures customers can always start and complete rides without manually adding funds.

Overview

When enabled, the system monitors wallet balances and automatically charges the customer's saved payment method when their balance drops too low. This creates a seamless riding experience where customers don't need to worry about running out of funds mid-ride.

Key Features

• Automatic charging - Charges saved payment method when balance is low
• Configurable threshold - Set the trigger point for automatic top-ups
• Configurable amount - Set how much to add each time
• Dual consent required - Both operator and customer must enable
• Stripe integration - Secure off-session payments via Stripe
• Concurrent protection - Database locks prevent duplicate charges

How It Works

Wallet Balance: $4.50
Threshold: $5.00
Top-Up Amount: $15.00

1. Customer starts ride
2. System checks: $4.50 ≤ $5.00 threshold
3. Auto top-up triggered
4. Stripe charges default card $15.00
5. New balance: $19.50
6. Ride proceeds normally

Requirements

Auto top-up requires ALL of the following:

Operator Configuration

Enabling Auto Top-Up

Configuration Options

Trigger Level (Threshold)

The wallet balance at which auto top-up activates.

Recommendations:

• Set threshold slightly higher than your average ride cost
• Consider your unlock fee + typical ride duration
• Higher thresholds = more frequent small charges

Top-Up Amount

How much to add to the wallet each time.

Recommendations:

• Should cover 2-4 typical rides
• Balance between convenience and transaction fees
• Higher amounts = fewer transactions

Best Practices

1. Set threshold above ride cost - Ensure customers can complete at least one ride
2. Balance amount vs. frequency - Higher amounts mean fewer Stripe fees
3. Communicate to customers - Make sure customers know auto top-up is available
4. Monitor declined charges - Check for failed auto top-ups regularly

Customer Experience

Enabling Auto Top-Up

Customers enable auto top-up in the mobile app:

1. Open Wallet screen
2. Tap Auto Top-Up toggle
3. Confirm enablement
4. Ensure a default payment method is saved

What Customers See

• Toggle to enable/disable auto top-up
• Notification when auto top-up charges occur
• Transaction history shows "Auto top-up" entries
• Current wallet balance always visible

When Auto Top-Up Triggers

Auto top-up is checked at these moments:

Ride Start Flow

1. Customer taps "Unlock" on vehicle
2. System checks wallet balance
3. If balance ≤ threshold AND auto top-up enabled:
   a. Lock acquired to prevent duplicate charges
   b. Stripe PaymentIntent created
   c. Default payment method charged
   d. Wallet balance updated
   e. Lock released
4. Ride starts normally

Ride End Flow

1. Ride ends, cost calculated: $8.50
2. Current wallet: $4.00
3. Wallet insufficient, auto top-up triggered
4. $15.00 added → New balance: $19.00
5. Ride cost deducted: $19.00 - $8.50 = $10.50
6. Customer sees final balance: $10.50

Technical Details

Database Fields

Subaccounts table:

Customers table:

Concurrency Protection

The system uses database locks to prevent charging customers multiple times:

1. Before charging, acquire lock via acquire_auto_topup_lock RPC
2. Lock has 2-minute TTL (auto-expires if process fails)
3. If lock already held, wait and check if balance increased
4. After charging, release lock via release_auto_topup_lock RPC
5. Idempotency key prevents Stripe duplicate charges

Error Handling

Troubleshooting

Auto Top-Up Not Working

1. Check subaccount setting - Verify auto_topup_enabled is true in Settings
2. Check customer setting - Verify customer has enabled in app
3. Check payment method - Customer needs a saved default card
4. Check Stripe customer - Customer needs stripe_customer_id
5. Check balance - May already be above threshold

Duplicate Charges

The system prevents duplicates via:

• Database lock on customer record
• Stripe idempotency keys
• Balance re-check after lock acquisition

If duplicates occur, check:

1. Lock release failures in logs
2. Stripe webhook processing
3. Database connection issues

Failed Charges

Common reasons for failed auto top-up:

Test Mode

For internal testing, the system automatically uses Stripe test mode for @levyelectric.com email addresses. This allows testing auto top-up flows without real charges.

Customer email: test@levyelectric.com
→ Uses STRIPE_TEST_SECRET_KEY
→ Test cards work (4242 4242 4242 4242)
→ No real charges processed

API Reference

Check Auto Top-Up Capability

import { canProcessAutoTopup } from '@/lib/auto-topup'

const canTopup = await canProcessAutoTopup(customerId, vehicleId)
// Returns: boolean

Process Auto Top-Up

import { processAutoTopup } from '@/lib/auto-topup'

const result = await processAutoTopup(customerId, vehicleId, skipThresholdCheck)
// Returns: { success, amountCents, error?, newWalletBalance? }

Toggle Customer Preference (Mobile API)

POST /api/mobile/payment
{
  "action": "toggle-auto-topup",
  "enabled": true
}