Wallet Management

Every customer has a single wallet balance (wallet_balance) that funds rides. This guide covers how the wallet works, how operators can adjust it, how auto top-up is configured, and how refunds interact with the wallet.

The Wallet Balance

There is one effective balance per customer: wallet balance. All manual adjustments (credits, bonuses, fees, debits) and automated flows (ride charges, refunds, auto top-ups) increase or decrease this single balance.

You'll also see a bonus column in the customer list and customer detail page. This is a legacy display-only field populated by customer imports — it is not consumed separately during ride payment and is not modified by the dashboard "Add Bonus" action. Treat it as historical context, not a live balance.

How Payments Are Applied to a Ride

Minimum Balance to Start a Ride

Customers must have at least $0.50 in the wallet to start a ride, unless they qualify for an exemption.

Wallet-check exemption (start a ride with $0 wallet): the customer must have both

1. An active subscription or an active ride package with remaining rides/minutes, and
2. A saved payment method on file.

Negative Balances

The wallet is allowed to go negative. This happens when:

• A Charge Fee is applied that exceeds current balance.
• A ride cost exceeds the wallet balance and the card charge fails.
• Operator uses Reduce Balance for an amount greater than current balance.

When Charge Fee causes the balance to cross from positive to negative, the customer automatically receives a push notification informing them of the negative balance.

Accessing Wallet Information

Customer List

The list shows each customer's wallet balance and the legacy bonus amount (if any) in separate columns.

Customer Detail Page

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

• Current wallet balance and bonus amount
• A Wallet dropdown in the action bar with: Add Bonus, Charge Fee, Reduce Balance
• A View Wallet Activity link to the full transaction history

Wallet Activity Page

The activity page lists every wallet_transactions row for the customer, including:

• Date and description
• Reference type (ride, topup, manual_bonus, manual_charge, manual_reduce_balance, stripe_charge, etc.)
• Amount (credit in green, debit in red)
• Running balance_after

Adding Wallet Credits

The dashboard exposes three actions in the customer's Wallet dropdown. All three write to the single wallet_balance and log a wallet_transactions row.

Add Bonus

Promotional or goodwill credit. Increases wallet balance.

• Transaction: type: 'credit', reference_type: 'manual_bonus'
• Notification: none
• API: POST /api/customers/bonus

{
  "customer_uuid": "customer-uuid",
  "amount_usd": 5.00
}

Accepted identifier fields (provide at least one): customer_uuid, customer_number, auth_uid, email, or customer_identifier.

Charging Fees & Reducing Balance

Charge Fee

For damages, lost equipment, parking violations, and similar penalties.

• Transaction: type: 'debit', reference_type: 'manual_charge'
• Can go negative: yes
• Notification: push notification sent when balance crosses from positive to negative
• Permission: requires customer:charge — analysts and service technicians are blocked
• API: POST /api/customers/charge

Reduce Balance

For silent corrections and adjustments that shouldn't notify the customer.

• Transaction: type: 'debit', reference_type: 'manual_reduce_balance'
• Can go negative: yes (same behavior as Charge Fee)
• Notification: never
• Permission: requires customer:charge
• API: POST /api/customers/reduce-balance

Charge Fee vs. Reduce Balance

Refunds: Always Against the Ride

Use one of these two endpoints depending on the situation:

Fare adjustment — when the ride was overcharged (e.g. customer was billed for time they didn't use):

POST /api/rides/[id]/adjust-fare
{
  "newTotalCost": 8.50,
  "reason": "Adjusted to reflect actual ride duration"
}

This recalculates tax, adjusts the ride, credits the wallet if the customer overpaid, and updates net_deposited.

Refund — when the fare is correct but the customer deserves money back:

POST /api/rides/[id]/refunds
{
  "destination": "wallet",
  "mode": "full",
  "reason": "Rider compensation"
}

destination can be wallet or card. mode can be full or partial (with an amount). The API refunds against what was actually paid (card or wallet), records it in ride_refunds, and updates net_deposited.

For goodwill credits not tied to a specific ride, use Add Bonus on the customer detail page.

Bulk Wallet Processing

The Bulk Wallet Processing action on the customer list is not a credit-upload tool. It's a collection tool that charges saved payment methods for customers with negative wallet balances. Select customers (or Select All), click Process, and the system attempts to charge each saved payment method for the amount needed to bring the wallet back to zero.

There is no CSV upload flow for bulk-adding credits today — add them one customer at a time from the dashboard or script the /api/customers/bonus endpoint.

Transaction History

Common reference_type values

The wallet activity UI groups and labels these for operators — the raw values above are what you'll see in the database and in API responses.

Auto Top-up

Auto top-up automatically replenishes a customer's wallet when their balance falls below a threshold, charging their default payment method.

How It Works

1. Customer's wallet balance drops below the threshold (typically during a ride-start or ride-payment check).
2. System charges the default payment method for the configured top-up amount.
3. Wallet is credited.
4. Customer receives a push notification confirming the top-up.

Configuration (both must be true)

• Customer setting: auto_topup_enabled on the customer record — customers opt in during registration (we frame auto top-up as a way to keep the vehicle from being disabled mid-ride; nearly all customers enable it).
• Subaccount setting: auto_topup_enabled on the subaccount, with auto_topup_amount_cents and auto_topup_threshold_cents.

Defaults

Troubleshooting Auto Top-up

1. Verify the customer has auto_topup_enabled.
2. Verify the subaccount has auto_topup_enabled and sane amount/threshold values.
3. Confirm the customer has a valid default payment method.
4. Check Stripe for declines.
5. Look in wallet_transactions for recent topup entries.

Best Practices

1. Document every manual adjustment — operator identity is stored, but a reason in the description helps future audits.
2. Use the ride refund flow for ride issues — never compensate ride problems with a direct wallet credit, or partner payouts and tax accounting will be wrong.
3. Reserve Add Bonus for promotions and goodwill not tied to a specific ride.
4. Restrict permissions — only admin roles and above should have customer:charge.

Troubleshooting

Credit not appearing in the customer app

• Confirm the transaction is in the customer's wallet activity.
• Ask the customer to force-close and reopen the app.
• Verify you adjusted the correct customer.

Wallet balance looks wrong

• Review recent transactions for unexpected debits or duplicate credits.
• Check ride history for automatic deductions (reference_type: 'ride').
• If the balance doesn't match the sum of transactions, escalate — customers.wallet_balance may be out of sync with wallet_transactions.

Customer says their ride refund didn't apply

• Open the ride detail page and check the Refunds section.
• Confirm the refund was processed via /api/rides/[id]/refunds or /api/rides/[id]/adjust-fare (not a direct wallet credit).
• Cross-reference the customer's wallet activity for a matching ride_refund entry.