feat: replace Stripe Global Payouts with manual bank transfer system for France compliance
- Replace Stripe automatic payouts with manual admin-processed bank transfers - Add banking information fields (IBAN, bank name, account holder) to User model - Implement manual payout workflow: pending → approved → processing → completed - Add comprehensive admin interface for payout review and processing - Update Payout model with manual processing fields and workflow methods - Add transfer reference tracking and rejection/failure handling - Consolidate all migration fragments into clean "create" migrations - Add comprehensive documentation for manual payout workflow - Fix Event payout_status enum definition and database column issues This addresses France's lack of Stripe Global Payouts support by implementing a complete manual bank transfer workflow while maintaining audit trails and proper admin controls. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kbe
157
docs/manual-payout-workflow.md
Normal file
157
docs/manual-payout-workflow.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user