Customer Wallets & Bonuses

Levy Fleets provides a flexible wallet and bonus system that allows customers to store credits for rides and enables operators to reward customers with promotional bonuses. This guide covers everything from understanding the balance types to managing wallet transactions and bonus credits.

Understanding Wallets vs. Bonuses

The system maintains two separate balance types for each customer:

How Payments Are Applied

Example: Customer has $5.00 bonus, $10.00 wallet, and ride costs $12.00

1. Bonus applied first: $5.00 bonus → $0.00 bonus remaining
2. Wallet applied second: $7.00 from wallet → $3.00 wallet remaining
3. Card charged: $0.00 (ride fully covered by credits)

If the ride cost $20.00 instead:

1. Bonus: $5.00 → $0.00 remaining
2. Wallet: $10.00 → $0.00 remaining
3. Card charged: $5.00

Minimum Balance Requirements

To start a ride, customers must have a minimum wallet balance of $0.50, unless they qualify for a wallet check exemption (see Ride Eligibility below).

Ride Eligibility & Wallet Check Exemptions

Customers can skip the wallet balance check if ALL of the following are true:

1. Customer has an active subscription OR an active ride package with remaining rides/minutes
2. Customer has a saved payment method on file

This allows subscription and package customers to ride even with $0 wallet balance, since their rides are covered by their purchased plan.

Negative Balances

Wallet balances can go negative in certain situations:

• When operators charge a fee that exceeds the current balance
• When a ride cost exceeds available credits and card charge fails

Accessing Wallet Information

From Customer List

The customer list displays wallet and bonus balances in separate columns:

• Wallet: Shows current wallet credit amount
• Bonus: Shows current bonus amount

From Customer Detail Page

Navigate to Dashboard > Customers > [Customer] to see:

• Wallet Balance Card: Current balance with "Add Credit" button
• Bonus Balance Card: Current bonus amount
• View Wallet Activity: Link to detailed transaction history

Wallet Activity Page

Access detailed transaction history at: Dashboard > Customers > [Customer] > Wallet Activity

This page displays:

• Complete list of wallet credit transactions
• Date and time of each transaction
• Transaction description
• Source/method of credit
• Amount (credits shown in green, debits in red)
• Running balance after each transaction

Adding Wallet Credits

Manual Credit (Individual Customer)

1. Navigate to the customer's detail page
2. In the Wallet section, click Add Credit (or the "+" button)
3. Enter the credit amount
4. Add an optional note explaining the reason
5. Click Add Credit to apply

The credit appears immediately in:

• Customer's wallet balance
• Wallet activity history
• Customer's mobile app

Common Reasons for Manual Credits

Charging Fees & Reducing Balance

Charge Fee

Use "Charge Fee" to apply charges for damages, lost equipment, parking violations, or other penalties.

How to Charge a Fee:

1. Navigate to customer detail page
2. Click Wallet dropdown in action bar
3. Select Charge Fee
4. Enter the amount
5. Add a description/reason
6. Click Charge Fee

API Endpoint: POST /api/customers/charge

{
  "customerIdentityId": "customer-identity-uuid",
  "amount_usd": 25.00,
  "description": "Parking violation fee"
}

Reduce Balance (Manual Debit)

Use "Reduce Balance" for corrections, adjustments, or silent debits that shouldn't notify the customer.

How to Reduce Balance:

1. Navigate to customer detail page
2. Click Wallet dropdown in action bar
3. Select Reduce Balance
4. Enter the amount
5. Add a reason/note
6. Click Reduce Balance

Key Behaviors:

• No notification: Customer is not notified of the deduction
• Cannot go negative: Balance stops at $0 (unlike Charge Fee)
• Creates transaction record: Logged as type debit with reference manual_reduce_balance

API Endpoint: POST /api/customers/reduce-balance

{
  "customerUuid": "customer-uuid",
  "amount_usd": 10.00,
  "description": "Correction for duplicate credit"
}

Charge Fee vs. Reduce Balance

Bulk Wallet Processing

For adding credits to multiple customers at once:

1. Navigate to Dashboard > Customers
2. Click Bulk Wallet Processing in the page header
3. Prepare your CSV file with the required format
4. Upload the CSV file
5. Review the preview showing all changes
6. Click Process to apply all credits

CSV Format for Bulk Processing:

identifier,identifier_type,amount,note
cust_abc123,id,10.00,Holiday promotion
user@email.com,email,5.00,Service credit
+15551234567,phone,7.50,Referral bonus
12345,customer_number,15.00,Loyalty reward

Supported Identifier Types:

• id: Customer's internal UUID
• email: Customer's email address
• phone: Customer's phone number (include country code)
• customer_number: System-assigned customer number

Adding Bonus Credits

Via API

Bonus credits are typically added via the bonus API endpoint:

Endpoint: POST /api/customers/bonus

Request Body:

{
  "customerId": "customer-uuid-here",
  "amount": 5.00,
  "reason": "Referral bonus"
}

Response:

{
  "success": true,
  "newBalance": 5.00,
  "previousBalance": 0.00
}

Via Dashboard

From the customer detail page:

1. Locate the Bonus Balance section
2. Click Add Bonus (if available)
3. Enter the bonus amount
4. Add a reason/note
5. Click Apply Bonus

Bonus vs. Wallet: When to Use Which

Wallet Transaction Types

Credit Transactions

Credits increase the wallet balance:

Debit Transactions

Debits decrease the wallet balance:

Wallet Activity Details

Each transaction in the wallet activity page shows:

Date Column

• Transaction timestamp
• Displayed in the user's timezone
• Sortable by date

Description Column

• Human-readable description of the transaction
• Shows transaction type (Credit/Debit label)
• May include additional context

Source Column

Indicates where the transaction originated:

• Manual: Added by operator in dashboard
• Stripe: Card charge or refund
• System: Automated (promo, referral, etc.)
• Ride: Associated with a specific ride
• Bulk: From bulk processing operation

Amount Column

• Green with +: Credit (money added)
• Red with -: Debit (money removed)
• Displayed in the customer's currency

Balance After Column

• Shows the running balance after this transaction
• Useful for auditing and reconciliation

Auto-Topup System

The auto-topup feature automatically replenishes a customer's wallet when their balance falls below a configured threshold.

How Auto-Topup Works

1. Customer's wallet balance drops below the threshold
2. System detects low balance during ride start or payment
3. Automatic charge is processed to the customer's default payment method
4. Wallet is credited with the configured topup amount
5. Customer receives a push notification confirming the topup

Configuration Requirements

Customer Settings:

• auto_topup_enabled: Customer must enable this in their app settings

Subaccount Settings:

• auto_topup_enabled: Subaccount must have auto-topup feature enabled
• auto_topup_amount_cents: Amount to add (default: $15.00 / 1500 cents)
• auto_topup_threshold_cents: Balance trigger point (default: $5.00 / 500 cents)

Default Configuration

Example: With default settings, when a customer's balance drops below $5.00, the system automatically charges their card $15.00 and credits their wallet.

Auto-Topup Triggers

Auto-topup is triggered during:

• Ride start (when balance is checked)
• Payment processing (when wallet is depleted)

Safety Mechanisms

The system includes multiple protections:

1. Database Locks: Prevents concurrent auto-topup attempts from charging twice
2. Idempotency Keys: Stripe idempotency keys prevent duplicate charges even with network issues
3. Threshold Check: Only triggers when balance is actually below threshold
4. Test Mode: Accounts with @levyelectric.com emails use Stripe test mode

Viewing Auto-Topup Transactions

Auto-topup transactions appear in the customer's wallet activity with:

• Type: stripe_topup or auto_topup
• Description: "Auto top-up" or "Automatic wallet top-up"
• Source: System-generated

Troubleshooting Auto-Topup

Auto-topup not working?

1. Verify customer has enabled auto-topup in app settings
2. Confirm subaccount has auto-topup enabled
3. Check that customer has a valid default payment method
4. Verify the payment method isn't declined
5. Check for existing pending auto-topup transactions

Integration with Payment Methods

Payment Hierarchy

When a customer makes a purchase:

1. Check for active subscriptions with included rides
2. Apply bonus balance (if available)
3. Apply wallet balance (if available)
4. Trigger auto-topup (if enabled and balance below threshold)
5. Charge payment method (for remaining amount)

Partial Wallet Usage

If a ride costs more than available credits:

• Credits are fully consumed
• Remaining amount charged to card
• Transaction shows as "Partial wallet payment"

Stripe Integration

Wallet credits interact with Stripe payments:

• Refunds: Can go to wallet instead of card
• Failed charges: No wallet credit consumed
• Disputes: May result in wallet debit

Wallet Balance in Mobile App

Customers see their wallet information in the app:

Balance Display

• Current wallet balance prominently shown
• Bonus balance may be shown separately
• Combined "credit" balance in some views

Adding Funds (If Enabled)

• Customer can add wallet credits via card
• Configurable minimum/maximum amounts
• Instant credit upon successful charge

Transaction History

• Customers can view recent wallet activity
• Limited to credits and debits affecting balance
• Shows date, description, and amount

Subaccount Wallet Policies

Different subaccounts may have different wallet policies:

Wallet Top-up Settings

• Enabled/Disabled: Allow customer self-top-up
• Minimum Amount: Smallest allowed top-up
• Maximum Amount: Largest allowed top-up
• Suggested Amounts: Quick-select options in app

Balance Limits

• Maximum Balance: Prevent accumulating excess credits
• Low Balance Warning: Notify when running low

Reporting and Analytics

Summary Metrics

The customer list header shows:

• Total Wallet Value: Sum of all wallet balances
• Total Bonuses: Sum of all bonus balances

Export Options

Export wallet data for analysis:

1. Navigate to customer list
2. Apply desired filters
3. Click Export (if available)
4. Select fields including wallet and bonus columns

Auditing Wallet Changes

For financial auditing:

1. Access individual customer wallet activity
2. Review transaction history with timestamps
3. Cross-reference with ride history
4. Check manual credits against operator logs

API Reference

Get Customer Wallet Balance

Endpoint: GET /api/customers/{id}

Returns customer object including:

{
  "id": "customer-uuid",
  "wallet_balance": 25.00,
  "bonus": 10.00
}

Add Wallet Credit (API)

Endpoint: POST /api/customers/{id}/wallet

Request:

{
  "amount": 10.00,
  "reason": "Service credit",
  "type": "credit"
}

Add Bonus Credit (API)

Endpoint: POST /api/customers/bonus

Request:

{
  "customerId": "customer-uuid",
  "amount": 5.00,
  "reason": "Promotional bonus"
}

Get Wallet Transactions

Endpoint: GET /api/customers/{id}/wallet/transactions

Query Parameters:

• limit: Number of transactions (default 50)
• offset: Pagination offset
• type: Filter by credit/debit

Best Practices

For Operators

1. Document all manual credits: Always include a reason/note
2. Use bonus for promotions: Reserve wallet for refunds/compensation
3. Regular audits: Review large or unusual credits periodically
4. Consistent policies: Apply similar credits for similar issues
5. Limit access: Restrict credit-adding permissions appropriately

For Customer Service

1. Check balance first: Before adding credit, verify current balance
2. Reference issues: Link credits to support tickets or ride IDs
3. Explain to customer: Tell them how credits will be applied
4. Set expectations: Credits apply to next ride automatically

For Finance Teams

1. Reconcile regularly: Match wallet credits to approved compensations
2. Monitor bulk operations: Review large batch credits
3. Track by reason: Categorize credits for reporting
4. Liability awareness: Wallet balances are a company liability

Troubleshooting

Credit not appearing in customer app

• Verify the credit was applied (check wallet activity)
• Have customer refresh the app or force-close/reopen
• Check if credit went to correct customer account
• Verify customer is logged into correct account

Wallet balance showing incorrectly

• Check recent transactions for unexpected debits
• Verify no duplicate credits were applied
• Review ride history for automatic deductions
• Check for system-generated adjustments

Bulk processing errors

• Verify CSV format matches expected structure
• Check that identifier type is correct for each row
• Ensure customer identifiers are valid
• Review error messages for specific failures

Customer says credit wasn't applied to ride

• Check ride payment breakdown in ride details
• Verify credit was in account before ride started
• Confirm bonus vs. wallet application order
• Review if credit expired (bonus only)