Customer Payment Methods

The payment methods system allows customers to store and manage their payment cards for use with Levy Fleets services. This guide covers how administrators can manage payment methods on behalf of customers through the dashboard, as well as how the system handles cards behind the scenes.

How Payment Methods Work

Storage Architecture

Payment methods are stored in two locations for security and efficiency:

1. Stripe - The actual payment method data (card number, expiry, CVC) is securely stored by Stripe
2. Levy Database - Only non-sensitive metadata is stored locally:
   • Stripe payment method ID
   • Card brand (Visa, Mastercard, etc.)
   • Last 4 digits
   • Card type
   • Default status

This architecture ensures PCI compliance while enabling efficient local queries.

Payment Method Flow

When a customer adds a card:

Database Schema

Payment Methods Table

Managing Payment Methods in the Dashboard

Accessing Payment Methods

1. Navigate to Dashboard > Customers
2. Click on a customer to view their profile
3. Find the Payment Methods section

Viewing Cards

The payment methods section displays:

• Card brand and last 4 digits (e.g., "VISA **** 4242")
• Date the card was added
• Default badge for the primary card
• Delete button for each card

Adding a Card

Test Mode Indicator

When adding cards for test accounts:

• A yellow banner shows "Test Mode Active"
• Use Stripe test card numbers (see below)
• No real charges will occur

Deleting a Card

1. Click the trash icon next to the card
2. Confirm the deletion in the dialog
3. Card is removed from both Stripe and the database

Test Mode

When Test Mode is Active

Test mode is automatically enabled when:

1. Super Admin Users - Any user with super_admin role
2. Internal Test Emails - Customers with @levyelectric.com email

Test Mode Behavior

In test mode:

• Uses test Stripe API keys
• Cards are stored in Stripe's test environment
• No real charges occur
• Setup intents use test endpoints
• Dashboard shows "Test Mode Active" indicator

Test Card Numbers

Use any valid future expiry date and any 3-digit CVC (4 digits for Amex).

Default Payment Method

Automatic Default Selection

When a customer adds their first payment method, it automatically becomes the default. This ensures there's always a usable payment method for:

• Wallet top-ups
• Auto top-up charges
• Payment retries

How Default is Determined

1. First card added is default
2. If default card is deleted, oldest remaining card becomes default

How Default is Used

The default payment method is used for:

• Auto Top-Up - Automatic wallet replenishment
• Payment Retries - Recovering negative wallet balances
• Off-Session Charges - Any charge initiated without customer presence

Integration with Payment Retry System

Payment methods play a critical role in the automatic payment retry system for recovering negative wallet balances.

How Payment Methods Are Used for Retries

When a customer's wallet goes negative, the system creates a payment retry job that:

1. Tries the default payment method first
2. Cycles through other cards ordered by creation date (oldest first)
3. Tracks which methods have been tried to avoid duplicate attempts within the same scheduling window
4. Resets the cycle when moving to a new day or week

Payment Method Cycling Order

1. Default payment method (is_default = true)
2. Oldest non-default card
3. Second oldest non-default card
4. ... continues through all cards

Importance of Multiple Cards

Customers with multiple payment methods have higher payment recovery rates because:

• If one card is declined, others are tried automatically
• Different cards may have different credit limits
• Bank-specific issues (temporary holds, fraud alerts) won't block payment entirely

Webhook Integration

Payment methods can also be created via Stripe webhooks when customers add cards through the mobile app:

setup_intent.succeeded

When a SetupIntent completes from the mobile app:

1. System looks up the customer by Stripe ID
2. Retrieves payment method details from Stripe
3. Saves card metadata to the database
4. Sets as default if it's the first card

payment_intent.succeeded

When a payment completes with a new payment method:

1. System checks if payment method already exists
2. If not, saves the new payment method
3. Updates customer's default if needed

Mobile App Integration

Adding Cards from Mobile

The mobile app uses Stripe's native SDK:

1. App requests ephemeral key from the server
2. Stripe CustomerSheet or PaymentSheet is presented
3. Customer enters card details in native Stripe UI
4. On success, setup_intent.succeeded webhook fires
5. Payment method is saved to database

Mobile Payment Actions

Security Considerations

PCI Compliance

The payment methods system maintains PCI compliance by:

1. Never handling raw card data - All card collection uses Stripe Elements/SDK
2. Storing only tokens - Only Stripe payment method IDs are stored
3. Masking card numbers - Only last 4 digits are saved
4. Secure transmission - All API calls use HTTPS
5. Webhook verification - All Stripe webhooks are signature-verified

Access Control

Payment method operations require authenticated users with appropriate roles:

Deletion Behavior

When deleting a payment method:

1. Stripe Detachment - Card is detached from Stripe customer
2. Local Deletion - Record removed from database
3. Default Reassignment - If default was deleted, next oldest becomes default
4. Both Environments Tried - System tries both live and test Stripe to ensure cleanup

Troubleshooting

Common Issues

"Failed to initialize Stripe form"

Cause: Setup intent creation failed

Solutions:

1. Check Stripe API keys are correct
2. Verify customer has a Stripe customer ID
3. Check Stripe dashboard for rate limits

Card not appearing after adding

Cause: Registration failed after SetupIntent

Solutions:

1. Check browser console for errors
2. Verify webhook is receiving setup_intent.succeeded
3. Check database for orphaned payment methods

"No payment method on file" during auto top-up

Cause: Customer has no payment methods or no default

Solutions:

1. Check payment_methods table for customer
2. Verify at least one card has is_default = true
3. Add a payment method if none exist

Test mode not working

Cause: Test keys not configured

Solutions:

1. Verify STRIPE_TEST_SECRET_KEY is set
2. Verify STRIPE_TEST_PUBLISHABLE_KEY is set
3. Ensure user is super_admin or customer has @levyelectric.com email

Diagnostic Queries

List customer's payment methods

SELECT
  pm.id,
  pm.brand,
  pm.last4,
  pm.is_default,
  pm.created_at,
  c.email
FROM payment_methods pm
JOIN customers c ON c.id = pm.customer_uuid
WHERE c.id = 'customer-uuid-here'
ORDER BY pm.created_at;

Find customers without payment methods

SELECT
  c.id,
  c.email,
  c.full_name,
  c.stripe_customer_id
FROM customers c
LEFT JOIN payment_methods pm ON pm.customer_uuid = c.id
WHERE pm.id IS NULL
  AND c.stripe_customer_id IS NOT NULL
ORDER BY c.created_at DESC
LIMIT 50;

Check for duplicate payment methods

SELECT
  stripe_payment_method_id,
  COUNT(*) as count
FROM payment_methods
GROUP BY stripe_payment_method_id
HAVING COUNT(*) > 1;

Best Practices

For Operators

1. Encourage multiple cards - Customers with backup cards have fewer payment failures
2. Monitor declined cards - Follow up with customers whose cards are failing
3. Use test mode - Always test card flows with test cards before production

For Customer Support

1. Verify before adding - Confirm customer identity before adding payment methods
2. Explain the process - Help customers understand why cards are needed
3. Document issues - Record any card-related problems for troubleshooting

What's Next?

• Stripe Setup - Configure Stripe integration
• Automatic Refunds - How automatic refunds work
• Damage Charges - Charging customers for damage