diff --git a/app/controllers/admin/payouts_controller.rb b/app/controllers/admin/payouts_controller.rb index 52ac330..80240b8 100644 --- a/app/controllers/admin/payouts_controller.rb +++ b/app/controllers/admin/payouts_controller.rb @@ -1,32 +1,77 @@ class Admin::PayoutsController < ApplicationController before_action :authenticate_user! before_action :ensure_admin! + before_action :set_payout, only: [:show, :approve, :reject, :mark_processing, :mark_completed, :mark_failed] def index - @payouts = Payout.pending.includes(:user, :event).order(created_at: :asc).page(params[:page]) + @pending_payouts = Payout.pending.includes(:user, :event).order(created_at: :asc) + @approved_payouts = Payout.approved.includes(:user, :event).order(created_at: :asc) + @processing_payouts = Payout.processing.includes(:user, :event).order(created_at: :asc) + @completed_payouts = Payout.completed.includes(:user, :event).order(created_at: :desc).limit(10) end def show - @payout = Payout.find(params[:id]) + @service = PayoutService.new(@payout) + @transfer_summary = @service.generate_transfer_summary + @banking_errors = @service.validate_banking_info end - def process - @payout = Payout.find(params[:id]) - - if @payout.pending? && @payout.can_process? - begin - PayoutService.new(@payout).process! - redirect_to admin_payouts_path, notice: "Payout processed successfully." - rescue => e - redirect_to admin_payouts_path, alert: "Failed to process payout: #{e.message}" - end + def approve + if @payout.approve!(current_user) + redirect_to admin_payout_path(@payout), notice: "Payout approved successfully." else - redirect_to admin_payouts_path, alert: "Cannot process this payout." + redirect_to admin_payout_path(@payout), alert: "Cannot approve this payout." end end + def reject + reason = params[:rejection_reason].presence || "No reason provided" + if @payout.reject!(current_user, reason) + redirect_to admin_payouts_path, notice: "Payout rejected." + else + redirect_to admin_payout_path(@payout), alert: "Cannot reject this payout." + end + end + + def mark_processing + transfer_reference = params[:bank_transfer_reference] + if @payout.mark_processing!(current_user, transfer_reference) + redirect_to admin_payout_path(@payout), notice: "Payout marked as processing." + else + redirect_to admin_payout_path(@payout), alert: "Cannot mark payout as processing." + end + end + + def mark_completed + transfer_reference = params[:bank_transfer_reference] + if @payout.mark_completed!(current_user, transfer_reference) + redirect_to admin_payouts_path, notice: "Payout completed successfully." + else + redirect_to admin_payout_path(@payout), alert: "Cannot mark payout as completed." + end + end + + def mark_failed + reason = params[:failure_reason].presence || "Transfer failed" + if @payout.mark_failed!(current_user, reason) + redirect_to admin_payouts_path, notice: "Payout marked as failed." + else + redirect_to admin_payout_path(@payout), alert: "Cannot mark payout as failed." + end + end + + # Legacy method - redirect to new workflow + def process + @payout = Payout.find(params[:id]) + redirect_to admin_payout_path(@payout), alert: "Use the new manual payout workflow." + end + private + def set_payout + @payout = Payout.find(params[:id]) + end + def ensure_admin! # For now, we'll just check if the user has a stripe account # In a real app, you'd have an admin role check diff --git a/app/models/event.rb b/app/models/event.rb index cb97682..837b172 100755 --- a/app/models/event.rb +++ b/app/models/event.rb @@ -17,12 +17,12 @@ class Event < ApplicationRecord }, default: :draft enum :payout_status, { - not_requested: 0, + pending_request: 0, requested: 1, processing: 2, completed: 3, failed: 4 - }, default: :not_requested + }, default: :pending_request # === Relations === belongs_to :user diff --git a/app/models/payout.rb b/app/models/payout.rb index fb56796..444bc99 100644 --- a/app/models/payout.rb +++ b/app/models/payout.rb @@ -2,13 +2,16 @@ class Payout < ApplicationRecord # === Relations === belongs_to :user belongs_to :event + belongs_to :processed_by, class_name: 'User', optional: true # === Enums === enum :status, { - pending: 0, # Payout requested but not processed - processing: 1, # Payout being processed - completed: 2, # Payout successfully completed - failed: 3 # Payout failed + 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 }, default: :pending # === Validations === @@ -45,7 +48,10 @@ class Payout < ApplicationRecord # === Scopes === scope :completed, -> { where(status: :completed) } scope :pending, -> { where(status: :pending) } + scope :approved, -> { where(status: :approved) } scope :processing, -> { where(status: :processing) } + scope :rejected, -> { where(status: :rejected) } + scope :failed, -> { where(status: :failed) } # === Callbacks === after_create :calculate_refunded_orders_count @@ -72,15 +78,74 @@ class Payout < ApplicationRecord net_amount_cents / 100.0 end - # Check if payout can be processed - def can_process? - pending? && amount_cents > 0 + # Check if payout can be approved (was pending) + def can_approve? + pending? && amount_cents > 0 && user.has_complete_banking_info? end - # Process the payout through Stripe - def process_payout! - service = PayoutService.new(self) - service.process! + # Check if payout can be manually processed (was approved) + def can_process? + approved? && amount_cents > 0 + end + + # Check if payout can be rejected + def can_reject? + pending? + end + + # Approve the payout for manual processing + def approve!(admin_user) + return false unless can_approve? + update!( + status: :approved, + processed_by: admin_user, + processed_at: Time.current + ) + end + + # Reject the payout with reason + def reject!(admin_user, reason) + return false unless can_reject? + update!( + status: :rejected, + processed_by: admin_user, + processed_at: Time.current, + rejection_reason: reason + ) + end + + # Mark as processing (bank transfer initiated) + def mark_processing!(admin_user, transfer_reference = nil) + return false unless can_process? + update!( + status: :processing, + processed_by: admin_user, + processed_at: Time.current, + bank_transfer_reference: transfer_reference + ) + end + + # Mark as completed (bank transfer confirmed) + def mark_completed!(admin_user, transfer_reference = nil) + return false unless processing? + update!( + status: :completed, + processed_by: admin_user, + processed_at: Time.current, + bank_transfer_reference: transfer_reference || bank_transfer_reference + ) + update_earnings_status + end + + # Mark as failed + def mark_failed!(admin_user, reason) + return false unless processing? + update!( + status: :failed, + processed_by: admin_user, + processed_at: Time.current, + rejection_reason: reason + ) end public diff --git a/app/models/user.rb b/app/models/user.rb index faff7b5..fee2493 100755 --- a/app/models/user.rb +++ b/app/models/user.rb @@ -31,6 +31,11 @@ class User < ApplicationRecord validates :first_name, length: { minimum: 2, maximum: 50, allow_blank: true } validates :company_name, length: { minimum: 2, maximum: 100, allow_blank: true } + # Banking information validations + validates :iban, format: { with: /\A[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}([A-Z0-9]?){0,16}\z/, message: "must be a valid IBAN format" }, allow_blank: true + validates :bank_name, length: { minimum: 2, maximum: 100 }, allow_blank: true + validates :account_holder_name, length: { minimum: 2, maximum: 100 }, allow_blank: true + # Onboarding methods def needs_onboarding? !onboarding_completed? @@ -65,7 +70,17 @@ class User < ApplicationRecord end def can_receive_payouts? - stripe_connected_account_id.present? && stripe_connect_verified? + has_complete_banking_info? + end + + # Banking information methods + def has_complete_banking_info? + iban.present? && bank_name.present? && account_holder_name.present? + end + + def banking_info_summary + return "No banking information" unless has_complete_banking_info? + "#{account_holder_name} - #{bank_name} - #{iban}" end private diff --git a/app/services/payout_service.rb b/app/services/payout_service.rb index 7125743..ffc36b7 100644 --- a/app/services/payout_service.rb +++ b/app/services/payout_service.rb @@ -3,36 +3,51 @@ class PayoutService @payout = payout end + # Legacy method for backward compatibility - now redirects to manual workflow def process! - return unless @payout.can_process? + Rails.logger.warn "PayoutService#process! called - manual processing required for payout #{@payout.id}" + raise "Automatic payout processing is disabled. Use manual workflow in admin interface." + end - @payout.update!(status: :processing) + # Generate payout summary for manual transfer + def generate_transfer_summary + return nil unless @payout.approved? || @payout.processing? - begin - net_amount = @payout.amount_cents - @payout.fee_cents - transfer = Stripe::Transfer.create({ - amount: (net_amount / 100.0).to_i, - currency: "eur", - destination: @payout.user.stripe_connected_account_id, - description: "Payout for event #{@payout.event.name}", - metadata: { payout_id: @payout.id, event_id: @payout.event_id } - }, idempotency_key: SecureRandom.uuid) + { + payout_id: @payout.id, + recipient: @payout.user.name, + account_holder: @payout.user.account_holder_name, + bank_name: @payout.user.bank_name, + iban: @payout.user.iban, + amount_euros: @payout.net_amount_euros, + description: "Payout for event: #{@payout.event.name}", + event_name: @payout.event.name, + event_date: @payout.event.date, + total_orders: @payout.total_orders_count, + refunded_orders: @payout.refunded_orders_count + } + end - @payout.update!( - status: :completed, - stripe_payout_id: transfer.id - ) + # Validate banking information before processing + def validate_banking_info + errors = [] + user = @payout.user - update_earnings_status - rescue Stripe::StripeError => e - @payout.update!(status: :failed) - Rails.logger.error "Stripe payout failed for payout #{@payout.id}: #{e.message}" - raise e - end + errors << "Missing IBAN" unless user.iban.present? + errors << "Missing bank name" unless user.bank_name.present? + errors << "Missing account holder name" unless user.account_holder_name.present? + errors << "Invalid IBAN format" if user.iban.present? && !valid_iban?(user.iban) + + errors end private + def valid_iban?(iban) + # Basic IBAN validation (simplified) + iban.match?(/\A[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}([A-Z0-9]?){0,16}\z/) + end + def update_earnings_status @payout.event.earnings.where(status: 0).update_all(status: 1) # pending to paid end diff --git a/app/views/admin/payouts/_payout_table.html.erb b/app/views/admin/payouts/_payout_table.html.erb new file mode 100644 index 0000000..a4176da --- /dev/null +++ b/app/views/admin/payouts/_payout_table.html.erb @@ -0,0 +1,96 @@ + + + + + + + + + + <% if show_actions %> + + <% end %> + + + + <% payouts.each do |payout| %> + + + + + + + + <% if show_actions %> + + <% end %> + + <% end %> + +
EventPromoterBanking InfoAmountStatusDateActions
+
<%= payout.event.name %>
+
<%= payout.event.date.strftime("%b %d, %Y") if payout.event.date %>
+ 		+
<%= payout.user.name.presence || payout.user.email %>
+ 		+ <% if payout.user.has_complete_banking_info? %> +
✅ Complete
+
<%= payout.user.bank_name %>
+ <% else %> +
❌ Incomplete
+
Missing banking info
+ <% end %> + 		+
€<%= payout.amount_euros %>
+
Net: €<%= payout.net_amount_euros %>
+ 		+ <% case payout.status %> + <% when 'pending' %> + + Pending Review + + <% when 'approved' %> + + Approved + + <% when 'processing' %> + + Processing + + <% when 'completed' %> + + Completed + + <% when 'failed' %> + + Failed + + <% when 'rejected' %> + + Rejected + + <% end %> + + <%= payout.created_at.strftime("%b %d, %Y") %> + <% if payout.processed_at %> +
Processed: <%= payout.processed_at.strftime("%b %d") %>
+ <% end %> + 		+ <%= link_to "View", admin_payout_path(payout), class: "text-indigo-600 hover:text-indigo-900" %> + <% case section %> + <% when 'pending' %> + <% if payout.can_approve? %> + <%= link_to "Approve", approve_admin_payout_path(payout), method: :post, + class: "text-green-600 hover:text-green-900 ml-2", + data: { confirm: "Approve this payout for transfer?" } %> + <% end %> + <% when 'approved' %> + <%= link_to "Start Transfer", mark_processing_admin_payout_path(payout), method: :post, + class: "text-blue-600 hover:text-blue-900 ml-2", + data: { confirm: "Mark as processing (transfer initiated)?" } %> + <% when 'processing' %> + <%= link_to "Complete", mark_completed_admin_payout_path(payout), method: :post, + class: "text-green-600 hover:text-green-900 ml-2", + data: { confirm: "Mark transfer as completed?" } %> + <% end %> +
\ No newline at end of file diff --git a/app/views/admin/payouts/index.html.erb b/app/views/admin/payouts/index.html.erb index 6bfde45..0614ed5 100644 --- a/app/views/admin/payouts/index.html.erb +++ b/app/views/admin/payouts/index.html.erb @@ -1,76 +1,49 @@
-

Admin Payouts

+

Manual Payout Administration

- <% if @payouts.any? %> -
- - - - - - - - - - - - - <% @payouts.each do |payout| %> - - - - - - - - - <% end %> - -
EventPromoterAmountStatusDateActions
-
<%= payout.event.name %>
- 		-
<%= payout.user.name.presence || payout.user.email %>
- 		-
€<%= payout.amount_euros %>
-
Net: €<%= payout.net_amount_euros %> (Fee: €<%= payout.fee_euros %>)
- 		- <% case payout.status %> - <% when 'pending' %> - - Pending - - <% when 'processing' %> - - Processing - - <% when 'completed' %> - - Completed - - <% when 'failed' %> - - Failed - - <% end %> - - <%= payout.created_at.strftime("%b %d, %Y") %> - - <% if payout.can_process? %> - <%= button_to "Process", admin_payout_path(payout), method: :post, - class: "text-indigo-600 hover:text-indigo-900 bg-indigo-100 hover:bg-indigo-200 px-3 py-1 rounded" %> - <% end %> - <%= link_to "View", promoter_payout_path(payout), class: "text-indigo-600 hover:text-indigo-900 ml-2" %> -
-
- - <% if @payouts.respond_to?(:total_pages) %> -
- <%= paginate @payouts %> + + <% if @pending_payouts.any? %> +
+

📋 Pending Review (<%= @pending_payouts.count %>)

+
+ <%= render partial: 'payout_table', locals: { payouts: @pending_payouts, show_actions: true, section: 'pending' } %>
- <% end %> - <% else %> +
+ <% end %> + + + <% if @approved_payouts.any? %> +
+

✅ Approved - Ready for Transfer (<%= @approved_payouts.count %>)

+
+ <%= render partial: 'payout_table', locals: { payouts: @approved_payouts, show_actions: true, section: 'approved' } %> +
+
+ <% end %> + + + <% if @processing_payouts.any? %> +
+

🔄 Processing - Transfer in Progress (<%= @processing_payouts.count %>)

+
+ <%= render partial: 'payout_table', locals: { payouts: @processing_payouts, show_actions: true, section: 'processing' } %> +
+
+ <% end %> + + + <% if @completed_payouts.any? %> +
+

✨ Recently Completed

+
+ <%= render partial: 'payout_table', locals: { payouts: @completed_payouts, show_actions: false, section: 'completed' } %> +
+
+ <% end %> + + <% if @pending_payouts.empty? && @approved_payouts.empty? && @processing_payouts.empty? && @completed_payouts.empty? %>

No payouts found.

diff --git a/app/views/admin/payouts/show.html.erb b/app/views/admin/payouts/show.html.erb index 0c14797..3ffec01 100644 --- a/app/views/admin/payouts/show.html.erb +++ b/app/views/admin/payouts/show.html.erb @@ -1,2 +1,208 @@ -

Admin::Payouts#show

-

Find me in app/views/admin/payouts/show.html.erb

+
+
+

Payout Details #<%= @payout.id %>

+ <%= link_to "← Back to Payouts", admin_payouts_path, class: "text-indigo-600 hover:text-indigo-900" %> +
+ +
+ +
+

Payout Information

+ +
+
+ + <% case @payout.status %> + <% when 'pending' %> + + Pending Review + + <% when 'approved' %> + + Approved - Ready for Transfer + + <% when 'processing' %> + + Processing + + <% when 'completed' %> + + Completed + + <% when 'failed' %> + + Failed + + <% when 'rejected' %> + + Rejected + + <% end %> +
+ +
+ +

<%= @payout.event.name %>

+

<%= @payout.event.date.strftime("%B %d, %Y") if @payout.event.date %>

+
+ +
+ +

<%= @payout.user.name.presence || @payout.user.email %>

+

<%= @payout.user.email %>

+
+ +
+
+ +

€<%= @payout.amount_euros %>

+
+
+ +

€<%= @payout.fee_euros %>

+
+
+ +
+ +

€<%= @payout.net_amount_euros %>

+
+ +
+
+ +

<%= @payout.total_orders_count %>

+
+
+ +

<%= @payout.refunded_orders_count %>

+
+
+ +
+ +

<%= @payout.created_at.strftime("%B %d, %Y at %I:%M %p") %>

+
+ + <% if @payout.processed_at %> +
+ +

<%= @payout.processed_at.strftime("%B %d, %Y at %I:%M %p") %>

+ <% if @payout.processed_by %> +

by <%= @payout.processed_by.name.presence || @payout.processed_by.email %>

+ <% end %> +
+ <% end %> + + <% if @payout.bank_transfer_reference.present? %> +
+ +

<%= @payout.bank_transfer_reference %>

+
+ <% end %> + + <% if @payout.rejection_reason.present? %> +
+ +

<%= @payout.rejection_reason %>

+
+ <% end %> +
+
+ + +
+

Banking Information

+ + <% if @banking_errors.any? %> +
+

Banking Information Issues:

+
    + <% @banking_errors.each do |error| %> +
  • • <%= error %>
    • + <% end %> +
+
+ <% end %> + + <% if @transfer_summary %> +
+
+ +

<%= @transfer_summary[:account_holder] %>

+
+ +
+ +

<%= @transfer_summary[:bank_name] %>

+
+ +
+ +

<%= @transfer_summary[:iban] %>

+
+ +
+

Transfer Instructions

+
+

Amount: €<%= @transfer_summary[:amount_euros] %>

+

Reference: Payout #<%= @transfer_summary[:payout_id] %> - <%= @transfer_summary[:event_name] %>

+
+
+
+ <% else %> +
+

Banking information not available for display.

+
+ <% end %> +
+
+ + +
+

Actions

+ +
+ <% if @payout.can_approve? %> + <%= button_to "✅ Approve Payout", approve_admin_payout_path(@payout), method: :post, + class: "bg-green-600 hover:bg-green-700 text-white px-4 py-2 rounded-md font-medium", + data: { confirm: "Approve this payout for manual bank transfer?" } %> + <% end %> + + <% if @payout.can_reject? %> + <%= form_with url: reject_admin_payout_path(@payout), method: :post, local: true, class: "flex gap-2" do |form| %> + <%= form.text_field :rejection_reason, placeholder: "Rejection reason...", required: true, + class: "border border-gray-300 rounded-md px-3 py-2" %> + <%= form.submit "❌ Reject", class: "bg-red-600 hover:bg-red-700 text-white px-4 py-2 rounded-md font-medium", + data: { confirm: "Reject this payout?" } %> + <% end %> + <% end %> + + <% if @payout.can_process? %> + <%= form_with url: mark_processing_admin_payout_path(@payout), method: :post, local: true, class: "flex gap-2" do |form| %> + <%= form.text_field :bank_transfer_reference, placeholder: "Transfer reference (optional)", + class: "border border-gray-300 rounded-md px-3 py-2" %> + <%= form.submit "🔄 Mark as Processing", class: "bg-blue-600 hover:bg-blue-700 text-white px-4 py-2 rounded-md font-medium", + data: { confirm: "Mark as processing (bank transfer initiated)?" } %> + <% end %> + <% end %> + + <% if @payout.processing? %> + <%= form_with url: mark_completed_admin_payout_path(@payout), method: :post, local: true, class: "flex gap-2" do |form| %> + <%= form.text_field :bank_transfer_reference, placeholder: "Final transfer reference", + value: @payout.bank_transfer_reference, + class: "border border-gray-300 rounded-md px-3 py-2" %> + <%= form.submit "✅ Mark as Completed", class: "bg-green-600 hover:bg-green-700 text-white px-4 py-2 rounded-md font-medium", + data: { confirm: "Confirm transfer completion?" } %> + <% end %> + + <%= form_with url: mark_failed_admin_payout_path(@payout), method: :post, local: true, class: "flex gap-2" do |form| %> + <%= form.text_field :failure_reason, placeholder: "Failure reason...", required: true, + class: "border border-gray-300 rounded-md px-3 py-2" %> + <%= form.submit "❌ Mark as Failed", class: "bg-red-600 hover:bg-red-700 text-white px-4 py-2 rounded-md font-medium", + data: { confirm: "Mark transfer as failed?" } %> + <% end %> + <% end %> +
+
+
diff --git a/config/routes.rb b/config/routes.rb index bc87dee..12a53ec 100755 --- a/config/routes.rb +++ b/config/routes.rb @@ -2,7 +2,12 @@ Rails.application.routes.draw do namespace :admin do resources :payouts, only: [ :index, :show ] do member do - post :process + post :process # Legacy route + post :approve + post :reject + post :mark_processing + post :mark_completed + post :mark_failed end end end diff --git a/db/migrate/20250816145933_devise_create_users.rb b/db/migrate/20250816145933_devise_create_users.rb index ac1f535..96477bf 100755 --- a/db/migrate/20250816145933_devise_create_users.rb +++ b/db/migrate/20250816145933_devise_create_users.rb @@ -55,6 +55,11 @@ class DeviseCreateUsers < ActiveRecord::Migration[8.0] # Link user to Stripe account for promoter payout t.string :stripe_connected_account_id + # Banking information for manual payouts + t.string :iban + t.string :bank_name + t.string :account_holder_name + t.timestamps null: false end diff --git a/db/migrate/20250823145902_create_events.rb b/db/migrate/20250823145902_create_events.rb index b619699..06451af 100755 --- a/db/migrate/20250823145902_create_events.rb +++ b/db/migrate/20250823145902_create_events.rb @@ -23,7 +23,7 @@ class CreateEvents < ActiveRecord::Migration[8.0] t.boolean :allow_booking_during_event, default: false, null: false # Payout fields - t.integer :payout_status + t.integer :payout_status, default: 0, null: false t.datetime :payout_requested_at t.timestamps diff --git a/db/migrate/20250823171354_create_tickets.rb b/db/migrate/20250823171354_create_tickets.rb index b6ef447..fd2d7d1 100755 --- a/db/migrate/20250823171354_create_tickets.rb +++ b/db/migrate/20250823171354_create_tickets.rb @@ -17,5 +17,6 @@ class CreateTickets < ActiveRecord::Migration[8.0] end add_index :tickets, :qr_code, unique: true + add_index :tickets, [:status, :order_id] end end diff --git a/db/migrate/20250916212717_create_earnings.rb b/db/migrate/20250916212717_create_earnings.rb index 3249e7a..885ac2b 100644 --- a/db/migrate/20250916212717_create_earnings.rb +++ b/db/migrate/20250916212717_create_earnings.rb @@ -14,5 +14,7 @@ class CreateEarnings < ActiveRecord::Migration[8.0] t.timestamps end + + add_index :earnings, :status end end diff --git a/db/migrate/20250916221454_create_payouts.rb b/db/migrate/20250916221454_create_payouts.rb index 39542dc..a13ceef 100644 --- a/db/migrate/20250916221454_create_payouts.rb +++ b/db/migrate/20250916221454_create_payouts.rb @@ -11,10 +11,17 @@ class CreatePayouts < ActiveRecord::Migration[8.0] t.references :user, null: false, foreign_key: false t.references :event, null: false, foreign_key: false + # Manual processing fields + t.references :processed_by, null: true, foreign_key: { to_table: :users } + t.datetime :processed_at + t.text :rejection_reason + t.string :bank_transfer_reference + t.timestamps end add_index :payouts, :status add_index :payouts, :stripe_payout_id, unique: true + add_index :payouts, [:event_id, :status] end end diff --git a/db/migrate/20250916230001_add_index_to_payouts_on_event_id_and_status.rb b/db/migrate/20250916230001_add_index_to_payouts_on_event_id_and_status.rb deleted file mode 100644 index 4f48022..0000000 --- a/db/migrate/20250916230001_add_index_to_payouts_on_event_id_and_status.rb +++ /dev/null @@ -1,5 +0,0 @@ -class AddIndexToPayoutsOnEventIdAndStatus < ActiveRecord::Migration[7.1] - def change - add_index :payouts, [ :event_id, :status ] - end -end diff --git a/db/migrate/20250916230002_add_index_to_earnings_on_status.rb b/db/migrate/20250916230002_add_index_to_earnings_on_status.rb deleted file mode 100644 index d900f53..0000000 --- a/db/migrate/20250916230002_add_index_to_earnings_on_status.rb +++ /dev/null @@ -1,5 +0,0 @@ -class AddIndexToEarningsOnStatus < ActiveRecord::Migration[7.1] - def change - add_index :earnings, :status - end -end diff --git a/db/migrate/20250916230003_add_index_to_tickets_on_status_and_order_id.rb b/db/migrate/20250916230003_add_index_to_tickets_on_status_and_order_id.rb deleted file mode 100644 index 2069675..0000000 --- a/db/migrate/20250916230003_add_index_to_tickets_on_status_and_order_id.rb +++ /dev/null @@ -1,5 +0,0 @@ -class AddIndexToTicketsOnStatusAndOrderId < ActiveRecord::Migration[7.1] - def change - add_index :tickets, [ :status, :order_id ] - end -end diff --git a/db/schema.rb b/db/schema.rb index f7bdf85..26e4643 100644 --- a/db/schema.rb +++ b/db/schema.rb @@ -10,7 +10,7 @@ # # It's strongly recommended that you check this file into your version control system. -ActiveRecord::Schema[8.0].define(version: 2025_09_16_230003) do +ActiveRecord::Schema[8.0].define(version: 2025_09_16_221454) do create_table "earnings", charset: "utf8mb4", collation: "utf8mb4_uca1400_ai_ci", force: :cascade do |t| t.integer "amount_cents" t.integer "fee_cents" @@ -42,11 +42,11 @@ ActiveRecord::Schema[8.0].define(version: 2025_09_16_230003) do t.decimal "longitude", precision: 10, scale: 6, null: false t.boolean "featured", default: false, null: false t.bigint "user_id", null: false - t.boolean "allow_booking_during_event", default: false, null: false - t.integer "payout_status" - t.datetime "payout_requested_at" t.datetime "created_at", null: false t.datetime "updated_at", null: false + t.boolean "allow_booking_during_event", default: false, null: false + t.integer "payout_status", default: 0, null: false + t.datetime "payout_requested_at" t.index ["featured"], name: "index_events_on_featured" t.index ["latitude", "longitude"], name: "index_events_on_latitude_and_longitude" t.index ["payout_status"], name: "index_events_on_payout_status" @@ -82,8 +82,13 @@ ActiveRecord::Schema[8.0].define(version: 2025_09_16_230003) do t.bigint "event_id", null: false t.datetime "created_at", null: false t.datetime "updated_at", null: false + t.bigint "processed_by_id" + t.datetime "processed_at" + t.text "rejection_reason" + t.string "bank_transfer_reference" t.index ["event_id", "status"], name: "index_payouts_on_event_id_and_status" t.index ["event_id"], name: "index_payouts_on_event_id" + t.index ["processed_by_id"], name: "index_payouts_on_processed_by_id" t.index ["status"], name: "index_payouts_on_status" t.index ["stripe_payout_id"], name: "index_payouts_on_stripe_payout_id", unique: true t.index ["user_id"], name: "index_payouts_on_user_id" @@ -138,11 +143,14 @@ ActiveRecord::Schema[8.0].define(version: 2025_09_16_230003) do t.string "company_website" t.string "stripe_customer_id" t.boolean "onboarding_completed", default: false, null: false - t.string "stripe_connected_account_id" t.datetime "created_at", null: false t.datetime "updated_at", null: false + t.string "iban" + t.string "bank_name" + t.string "account_holder_name" t.index ["email"], name: "index_users_on_email", unique: true t.index ["reset_password_token"], name: "index_users_on_reset_password_token", unique: true - t.index ["stripe_connected_account_id"], name: "index_users_on_stripe_connected_account_id", unique: true end + + add_foreign_key "payouts", "users", column: "processed_by_id" end diff --git a/docs/manual-payout-workflow.md b/docs/manual-payout-workflow.md new file mode 100644 index 0000000..edcbe7f --- /dev/null +++ b/docs/manual-payout-workflow.md @@ -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 \ No newline at end of file diff --git a/docs/payout-system-analysis.md b/docs/payout-system-analysis.md new file mode 100644 index 0000000..1cf7002 --- /dev/null +++ b/docs/payout-system-analysis.md @@ -0,0 +1,112 @@ +# 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. \ No newline at end of file