# Payout System Analysis Report

## Current Implementation Overview

The current payout system implemented on the `feat/stripe-global-payouts` branch uses **Stripe Connect** with **Stripe Transfers** to automatically process payouts to promoters. This implementation is **not compatible with France** as it relies on Stripe Global Payouts functionality.

## Architecture Analysis

### Core Components

1. **Models**
   - `Payout`: Tracks payout requests with statuses (pending, processing, completed, failed)
   - `User`: Contains `stripe_connected_account_id` for Stripe Connect integration
   - `Event`: Has payout eligibility and earnings calculation methods
   - `Earning`: Tracks individual order earnings (referenced in docs but may not be fully implemented)

2. **Services**
   - `PayoutService` (`app/services/payout_service.rb:13-19`): Processes payouts via `Stripe::Transfer.create`
   - `StripeConnectService`: Manages Stripe Connect account setup

3. **Controllers**
   - `Promoter::PayoutsController`: Handles promoter payout requests and viewing
   - `Admin::PayoutsController`: Handles admin payout processing

### Current Payout Flow

1. **Promoter Request**: Promoter requests payout for ended event via `Promoter::PayoutsController#create`
2. **Admin Processing**: Admin processes payout via `Admin::PayoutsController#process`
3. **Stripe Transfer**: `PayoutService` creates `Stripe::Transfer` to promoter's connected account
4. **Status Update**: Payout status updated to completed/failed based on Stripe response

### Key Issues for France

1. **Stripe Global Payouts Dependency**: The system uses `Stripe::Transfer.create` with `destination: stripe_connected_account_id` which requires Stripe Global Payouts
2. **Stripe Connect Requirement**: Users must have verified Stripe Connect accounts (`stripe_connected_account_id`)
3. **Automatic Processing**: System assumes automated Stripe processing capability

## Database Schema

### Payouts Table
- `amount_cents`: Gross payout amount
- `fee_cents`: Platform fees
- `status`: Enum (pending, processing, completed, failed)
- `stripe_payout_id`: Stripe transfer ID
- `total_orders_count`: Number of orders included
- `refunded_orders_count`: Number of refunded orders
- `user_id`: Promoter receiving payout
- `event_id`: Event for which payout is requested

### Users Table (Relevant Fields)
- `stripe_connected_account_id`: Stripe Connect account ID
- `is_professionnal`: Required for event management

## Compliance and Legal Considerations

### France-Specific Issues
1. **Stripe Global Payouts**: Not available in France as of current analysis
2. **Banking Regulations**: May require different approach for cross-border transfers
3. **Tax Reporting**: Manual payouts may require additional documentation

### Alternative Approaches Needed
1. **Manual Bank Transfers**: Admin-initiated SEPA transfers
2. **Payout Request System**: Promoters request, admins approve and process manually
3. **Documentation**: Enhanced record-keeping for manual transfers

## Recommendations

### Immediate Actions Required
1. **Disable Automatic Processing**: Remove Stripe Transfer functionality
2. **Implement Manual Workflow**: Create admin interface for manual payout processing
3. **Add Banking Information**: Collect IBAN/SWIFT details from promoters
4. **Update Status Flow**: Modify payout statuses for manual processing

### Proposed Manual Payout System
1. **Request Phase**: Promoters submit payout requests (existing functionality can be kept)
2. **Review Phase**: Admins review and approve requests
3. **Processing Phase**: Admins mark as "processing" and initiate bank transfer
4. **Completion Phase**: Admins confirm transfer completion manually

## Migration Strategy

### Phase 1: Immediate Fix
- Disable automatic Stripe processing
- Add manual processing interface for admins
- Update payout status workflow

### Phase 2: Enhanced Manual System
- Add banking information collection
- Implement approval workflow
- Add transfer documentation features

### Phase 3: Potential Automation
- Investigate France-compatible payment providers
- Implement API-based bank transfers if available
- Maintain manual fallback option

## Technical Debt

### Files Requiring Updates
- `app/services/payout_service.rb`: Remove Stripe Transfer logic
- `app/controllers/admin/payouts_controller.rb`: Add manual processing actions
- `app/models/user.rb`: Add banking information fields
- Database migrations: Add IBAN/banking fields to users table

### Testing Impact
- Update `test/services/payout_service_test.rb`
- Modify controller tests for manual workflow
- Add integration tests for manual payout flow

## Conclusion

The current Stripe Global Payouts implementation is not viable for France operations. A manual payout system must be implemented immediately to handle promoter payments through traditional banking methods while maintaining audit trails and proper documentation.