aperonight/docs/manual-payout-workflow.md

# Manual Payout Workflow

## Overview

This document describes the manual payout system implemented to replace Stripe Global Payouts, which is not available in France. The system allows promoters to request payouts for their events, and administrators to process these requests manually through bank transfers.

## Workflow Steps

### 1. Promoter Requests Payout
- Promoters can request payouts for ended events through the existing interface
- The system validates that banking information is complete before allowing requests
- Payout status is set to `pending`

### 2. Admin Review (Pending → Approved/Rejected)
**Admin Actions Available:**
- **Approve**: If all information is correct and banking details are valid
- **Reject**: If there are issues (missing info, invalid details, policy violations)

**What Admins Check:**
- Banking information completeness (IBAN, bank name, account holder)
- Event validity and earnings calculation
- Promoter eligibility

### 3. Manual Bank Transfer (Approved → Processing)
**Admin Actions:**
- **Mark as Processing**: When bank transfer is initiated
- Optional: Add transfer reference number
- Admin manually processes SEPA transfer through their banking system

### 4. Transfer Completion (Processing → Completed/Failed)
**Admin Actions:**
- **Mark as Completed**: When transfer is confirmed successful
- **Mark as Failed**: If transfer fails or is rejected by bank
- Update transfer reference if needed

## Banking Information Requirements

### For Promoters
Users must provide:
- **IBAN**: Valid IBAN format (validated by regex)
- **Bank Name**: Name of the banking institution
- **Account Holder Name**: Full name matching bank account

### IBAN Validation
- Basic format validation implemented
- Supports standard European IBAN format
- Regex: `/\A[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}([A-Z0-9]?){0,16}\z/`

## Database Schema Changes

### New User Fields
```ruby
add_column :users, :iban, :string
add_column :users, :bank_name, :string
add_column :users, :account_holder_name, :string
```

### New Payout Fields
```ruby
add_reference :payouts, :processed_by, foreign_key: { to_table: :users }
add_column :payouts, :processed_at, :datetime
add_column :payouts, :rejection_reason, :text
add_column :payouts, :bank_transfer_reference, :string
```

### Updated Payout Statuses
```ruby
enum :status, {
  pending: 0,           # Payout requested but not reviewed
  approved: 1,          # Payout approved by admin, ready for transfer
  processing: 2,        # Payout being processed (bank transfer initiated)
  completed: 3,         # Payout successfully completed
  failed: 4,            # Payout failed
  rejected: 5           # Payout rejected by admin
}
```

## Admin Interface

### Dashboard Sections
1. **Pending Review**: New requests requiring admin approval/rejection
2. **Approved**: Ready for manual bank transfer
3. **Processing**: Transfers in progress
4. **Recently Completed**: Completed transfers for reference

### Transfer Information Display
- Promoter banking details
- Transfer amount and reference
- Event information
- Validation warnings for incomplete banking info

## Security & Audit

### Audit Trail
- All status changes tracked with timestamp
- Admin user recorded for each action
- Transfer references stored for bank reconciliation

### Validation
- Banking information validated before approval
- IBAN format checking
- Complete information required before processing

## Migration from Stripe

### Immediate Changes
- ✅ Stripe Transfer functionality disabled
- ✅ Manual workflow implemented
- ✅ Banking information collection added
- ✅ Admin interface updated

### Legacy Support
- Original `PayoutService#process!` method redirects to manual workflow
- Existing payout request flow preserved for promoters
- Database backward compatible

## Usage Instructions

### For Administrators
1. Access admin payout dashboard at `/admin/payouts`
2. Review pending payouts for approval
3. For approved payouts, initiate bank transfers manually
4. Update payout status as transfers progress
5. Mark as completed when transfer is confirmed

### For Promoters
1. Ensure banking information is complete in profile
2. Request payouts for ended events as before
3. Monitor payout status through existing interface
4. Banking information must be valid IBAN format

## Error Handling

### Common Issues
- **Incomplete Banking Info**: Prevents approval until resolved
- **Invalid IBAN**: Validation error displayed to admin
- **Transfer Failures**: Can be marked as failed with reason

### Recovery
- Failed payouts can be retried after fixing issues
- Rejected payouts require new requests
- Banking information can be updated by promoters

## Future Enhancements

### Potential Improvements
1. Integration with banking APIs for automated transfers
2. Enhanced IBAN validation with checksum verification
3. Email notifications for status changes
4. Bulk transfer processing
5. Advanced reporting and reconciliation tools

### France-Specific Considerations
1. SEPA transfer compliance
2. Tax reporting requirements
3. AML/KYC documentation
4. Banking regulation compliance