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

add_column :users, :iban, :string
add_column :users, :bank_name, :string
add_column :users, :account_holder_name, :string

New Payout Fields

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

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