Payment and Billing Issues
This guide helps you diagnose and resolve payment-related issues in Levy Fleets, from failed transactions to billing discrepancies and refund problems.
Payment Systems
Levy Fleets supports two payment modes: Post-Paid (customers pay after rides) and Wallet (customers maintain a prepaid balance). The troubleshooting steps may vary depending on your configured mode.
Quick Reference: Payment Issue Categories
| Issue Type | Common Cause | Quick Fix |
|---|---|---|
| Payment declined | Insufficient funds / Card expired | Customer updates payment method |
| Wrong amount charged | Pricing misconfiguration | Review pricing rules |
| Refund not processed | Pending in queue | Wait 24-48 hours |
| Wallet balance wrong | Transaction not reflected | Check transaction history |
| Stripe error | API/integration issue | Check Stripe dashboard |
Payment Declined or Failed
Symptoms
- Customer reports card declined during ride start
- "Payment failed" error message
- Ride ended early due to payment issue
- Customer account blocked due to failed payment
Possible Causes
| Cause | Likelihood | How to Identify |
|---|---|---|
| Insufficient funds | High | Bank declined for NSF |
| Card expired | High | Check card expiration |
| Card limit reached | Medium | Daily/monthly spending limit |
| Fraud protection | Medium | Bank flagged transaction |
| Wrong CVV/ZIP | Medium | Validation failed |
| Card blocked | Low | Customer's bank blocked card |
| Stripe issue | Low | Check Stripe dashboard status |
Solutions
Review Transaction Details
Go to the customer profile and check the transaction history. Look for the failed payment entry and note any error codes or messages.
Check Stripe Dashboard
Log into your Stripe dashboard and search for the customer or transaction. Stripe provides detailed decline reasons.
Identify Decline Code
Common Stripe decline codes:
| Code | Meaning | Customer Action |
|---|---|---|
insufficient_funds | Not enough money | Use different card |
card_declined | General decline | Contact bank |
expired_card | Card expired | Update card |
incorrect_cvc | Wrong CVV | Re-enter card |
processing_error | Temporary | Try again later |
fraudulent | Suspected fraud | Contact bank |
Guide Customer to Update Payment
Direct the customer to update their payment method in the app:
- Open the app
- Go to Settings/Profile
- Select Payment Methods
- Add a new card or update existing
Clear Account Block
If the customer's account was blocked due to failed payment:
- Go to Customer profile
- Verify new payment method is added
- Verify wallet balance is positive
- Unblock the account
When to Escalate
- If Stripe dashboard shows "succeeded" but customer was still declined
- If multiple customers report declines simultaneously (possible system issue)
- If decline codes indicate potential fraud patterns
Customer Overcharged for Ride
Symptoms
- Customer claims they were charged more than expected
- Ride total seems too high for duration/distance
- Customer requesting refund for overcharge
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| Long pause included | High | Pause time billed at pause rate |
| Pricing tier applied | Medium | Base vs. premium pricing |
| No daily cap | Medium | Total exceeded expected maximum |
| Surge pricing active | Medium | Higher rates during peak times |
| Promo not applied | Medium | Customer expected discount |
| Billing calculation error | Low | System error |
Solutions
Review Ride Details
Open the ride detail page and examine:
- Total active time
- Total paused time
- Distance traveled
- Pricing breakdown
Check Pricing Configuration
Verify the pricing that was applied:
- Unlock fee amount
- Per-minute rate
- Per-minute pause rate (if applicable)
- Distance rate (if applicable)
- Daily cap amount
Verify Timeline
Review the ride timeline for:
- Start time
- Any pause periods
- End time
- Total duration calculation
Check for Promotions
Verify if a promo code or subscription should have applied:
- Was a promo code entered?
- Does customer have active subscription?
- Was it within promo validity period?
Issue Refund if Warranted
If the customer was genuinely overcharged:
- Go to customer wallet
- Add credit for the overcharge amount
- Note: "Refund for ride #XXXX - overcharge adjustment"
Price Calculation Reference
Standard ride price calculation:
Total = Unlock Fee + (Active Minutes x Per-Minute Rate) + (Pause Minutes x Pause Rate) + (Distance x Distance Rate)
With daily cap:
Total = MIN(Calculated Total, Daily Cap)
Customer Undercharged or Not Charged
Symptoms
- Ride completed but no charge recorded
- Transaction shows $0.00
- Revenue not appearing in reports
Possible Causes
| Cause | Likelihood | Description |
|---|---|---|
| Free ride promo | High | 100% discount applied |
| Payment processing delay | Medium | Charge still pending |
| Ride auto-cancelled | Medium | System cancelled before billing |
| Subscription package | Medium | Ride covered by subscription |
| Pricing not configured | Low | No pricing rules for vehicle model |
Solutions
Check Ride Status
Verify the ride status is "Completed" not "Cancelled". Cancelled rides may not be charged.
Review Applied Discounts
Check if any promotions or subscriptions were applied that result in $0 charge.
Check Pricing Configuration
Go to Pricing and verify:
- Pricing exists for the vehicle model
- Pricing is marked as "Active"
- Unlock fee and rates are set (not $0)
Check Transaction Log
Look for the transaction in customer history. It may be pending rather than missing.
Manually Bill if Needed
If a charge should have occurred but didn't:
- Calculate the correct amount
- Charge customer wallet (add negative credit)
- Document the manual adjustment
Wallet Balance Issues
Customer Wallet Shows Wrong Balance
Symptoms:
- Customer claims balance is incorrect
- Wallet shows different amount than expected
- Recent top-up not reflected
Possible Causes:
- Transaction not yet processed
- Bonus expired
- Charge not yet reflected
- Multiple transactions in progress
Solutions:
Check Transaction History
Review all recent transactions in the customer's wallet:
- Top-ups
- Ride charges
- Bonus additions/expirations
- Refunds
Verify Recent Activity
Check if there are pending transactions that haven't posted yet. Allow 5-10 minutes for processing.
Check Bonus Expiration
Bonus credits may have expired. Look for "Bonus Expired" entries in transaction history.
Recalculate Balance
Manually add up all transactions to verify the current balance is correct.
Adjust if Needed
If balance is genuinely wrong:
- Calculate the correct amount
- Add an adjustment credit with detailed note
- Document the discrepancy for audit
Customer Cannot Add Funds to Wallet
Symptoms:
- Top-up button fails
- Payment method charged but balance not updated
- Error message during top-up
Possible Causes:
- Payment method declined
- Stripe processing error
- App connectivity issue
- Wallet system temporarily down
Solutions:
- Check payment method - Verify card is valid and has funds
- Check Stripe dashboard - Look for successful or failed charges
- Wait and retry - Temporary processing delays are common
- Try different payment method - Rule out card-specific issues
- Clear app cache - Customer should clear app data and retry
- Manual credit addition - Operator can add credit manually as workaround
When to Escalate: If Stripe shows successful charge but wallet wasn't credited, contact support immediately with transaction ID.
Negative Wallet Balance
Symptoms:
- Customer wallet shows negative amount
- Customer cannot start new rides
- Account may be blocked
Possible Causes:
- Ride ended before payment processed
- Top-up payment was reversed/chargedback
- Refund was processed but original charge remains
Solutions:
Understand How Negative Balances Occur
Negative balances typically happen when:
- A ride was completed but payment failed
- A top-up was reversed by the customer's bank
- A chargeback was processed
Review Transaction History
Look for:
- Failed payment attempts
- Reversed transactions
- Chargebacks
Determine Resolution
Options:
- Collect payment: Customer adds funds to cover negative
- Write off: For small amounts, credit the difference
- Block account: For repeat offenders or fraud
Process Write-Off if Appropriate
For small uncollectible amounts:
- Add credit equal to negative balance
- Note: "Write-off - uncollectible balance"
- Document per your financial policy
Refund Issues
Refund Not Appearing in Customer's Account
Symptoms:
- Refund processed in dashboard but customer doesn't see it
- Wallet credit added but balance unchanged
- Bank refund not received
Possible Causes:
| Refund Type | Processing Time | Where to Check |
|---|---|---|
| Wallet Credit | Immediate | Customer wallet in dashboard |
| Card Refund | 3-10 business days | Customer's bank statement |
| Original Payment Reversal | 5-10 business days | Stripe dashboard |
Solutions:
Identify Refund Type
Determine if the refund was:
- Wallet credit (appears instantly in app)
- Payment refund (goes back to original payment method)
Verify Refund Was Processed
Check the customer's transaction history for the refund entry with correct amount and timestamp.
For Wallet Credits
- Should appear immediately
- Check customer wallet balance
- Have customer log out and back in
- Force refresh customer data
For Card Refunds
- Check Stripe dashboard for refund status
- Provide customer with refund transaction ID
- Advise 3-10 business days for bank processing
- Customer should contact their bank if not received after 10 days
Refund Requested but Cannot Process
Symptoms:
- Refund button disabled or missing
- Error when trying to process refund
- "Cannot refund this ride" message
Possible Causes:
- Insufficient permissions
- Refund already processed
- Original transaction too old
- Stripe refund limits reached
Solutions:
- Check permissions - Refund requires appropriate role (Admin, Fleet Manager)
- Check refund history - Ride may already have been refunded
- Check timeframe - Some payment processors limit refund windows (typically 120 days)
- Check Stripe limits - You cannot refund more than original charge
- Use wallet credit - If card refund fails, add wallet credit instead
- Escalate to admin - Higher permissions may be needed
Partial Refund Not Calculating Correctly
Symptoms:
- Want to refund part of ride but full amount showing
- Refund amount doesn't match expected partial
Possible Causes:
- System only supports full refunds for ride charges
- Calculation includes fees that can't be partially refunded
Solutions:
For partial refunds, use wallet credit:
- Calculate the partial refund amount
- Go to customer wallet
- Add credit for the partial amount
- Note: "Partial refund for ride #XXXX - reason"
Pricing Configuration Issues
Pricing Not Applying to Rides
Symptoms:
- Rides showing $0 charge when they shouldn't
- Default pricing applied instead of custom pricing
- Wrong rate being used
Possible Causes:
| Cause | Check |
|---|---|
| Pricing not active | Status should be "Active" |
| Wrong vehicle model | Pricing linked to wrong model |
| Date range expired | Check valid from/to dates |
| Subaccount mismatch | Pricing in different subaccount |
Solutions:
Verify Pricing is Active
Go to Pricing and confirm:
- Status is "Active" (not Draft or Inactive)
- Valid date range includes current date
- Pricing is in the correct subaccount
Check Vehicle Model Linking
Verify the pricing is associated with the correct vehicle model(s).
Check Priority
If multiple pricing rules exist, verify the correct one has higher priority.
Test with New Ride
Start a test ride to see which pricing is applied. Check the ride details for applied rates.
Dynamic Pricing Not Working
Symptoms:
- Surge pricing not activating during peak times
- Zone-based pricing not applying
- Time-based rates not changing
Solutions:
- Verify configuration - Check dynamic pricing rules are set up correctly
- Check schedule - Verify time-based rules match current time/timezone
- Check zone boundaries - Ensure vehicle is within dynamic pricing zone
- Check trigger conditions - Verify demand thresholds are being met
- Review ride details - Look at pricing breakdown to see what was applied
Stripe Integration Issues
Stripe Connection Not Working
Symptoms:
- "Stripe not connected" error
- Cannot process any payments
- Integration status shows error
Possible Causes:
- API keys invalid or expired
- Stripe account restricted
- Webhook configuration incorrect
- API version mismatch
Solutions:
Check Stripe Dashboard
Log into Stripe and verify:
- Account is in good standing
- No restrictions on the account
- API keys are valid
Verify API Keys
In Levy Fleets settings, verify:
- Publishable key is correct
- Secret key is correct
- Using correct keys (test vs. live)
Check Webhook Configuration
In Stripe webhook settings:
- Verify webhook URL is correct
- Verify webhook secret matches
- Check for failed webhook attempts
Review API Logs
Check Stripe's developer logs for:
- Failed API calls
- Error messages
- Rate limiting issues
When to Escalate: Contact support if you cannot resolve Stripe integration issues, providing:
- Stripe account ID
- Error messages seen
- Time when issues started
Stripe Fees Higher Than Expected
Symptoms:
- Processing fees seem too high
- Fees not matching expected rates
Solutions:
- Review Stripe pricing - Confirm your negotiated rates
- Check for international cards - Higher fees for non-domestic cards
- Check card types - Business/corporate cards may have higher fees
- Review Stripe billing - Check monthly invoice for itemized fees
- Contact Stripe - Discuss rate optimization if volume justifies
Subscription and Package Issues
Subscription Not Applying
Symptoms:
- Customer has subscription but being charged per-ride rates
- Subscription benefits not reflected
Possible Causes:
- Subscription expired
- Subscription paused
- Wrong subscription type for vehicle
- Subscription limits reached
Solutions:
- Check subscription status - Verify Active, not Paused/Cancelled
- Check expiration date - Subscription may have expired
- Check usage limits - Monthly ride/minute limits may be exhausted
- Check vehicle eligibility - Some subscriptions only cover certain vehicle types
- Renew subscription - If expired, customer needs to renew
Auto-Renewal Failed
Symptoms:
- Subscription expired unexpectedly
- Auto-renewal payment declined
- Customer wasn't notified of renewal failure
Solutions:
- Check payment method - Verify customer has valid payment method
- Check Stripe for decline reason - Review failed subscription charge
- Notify customer - Contact customer about payment issue
- Manually renew - After payment method updated, manually trigger renewal
- Review notification settings - Ensure renewal failure emails are configured
Financial Reporting Issues
Revenue Reports Don't Match
Symptoms:
- Dashboard revenue different from Stripe revenue
- Daily totals don't add up to monthly
- Export data doesn't match displayed data
Possible Causes:
- Different date ranges
- Filters applied
- Timezone differences
- Pending vs. completed transactions
- Refunds not accounted for
Solutions:
Align Date Ranges
Ensure you're comparing exactly the same date ranges, accounting for timezone.
Account for Refunds
Revenue in Levy Fleets is gross (before refunds). Stripe shows net (after refunds).
Check Transaction Status
Some transactions may be pending. Include all statuses for complete picture.
Use Same Timezone
Verify both systems are using the same timezone for date cutoffs.
Export Raw Data
Export transaction-level data from both systems and reconcile manually.
Best Practices for Preventing Payment Issues
Proactive Monitoring
-
Daily checks
- Review failed payment count
- Check Stripe dashboard for errors
- Review negative balance accounts
-
Weekly checks
- Reconcile revenue reports
- Review refund volume
- Check subscription renewal rates
-
Monthly checks
- Full financial reconciliation
- Review Stripe fees
- Audit write-offs and adjustments
Customer Communication
- Payment failure notifications - Ensure customers receive immediate alerts
- Renewal reminders - Send subscription renewal notices
- Balance warnings - Alert customers when wallet balance is low
- Receipt delivery - Confirm ride receipts are being sent
Need Help?
For payment issues that require investigation of Stripe transactions or complex refunds, contact support@levyelectric.com with:
- Customer email
- Transaction date and amount
- Stripe transaction ID (if available)
- Description of the issue