MS-170/feat: Split Refund System for Mixed Payments (Gift Cards & Vouchers)

🎯 Objective

Implement a flexible split refund system to handle orders paid with mixed payment methods (gift cards, vouchers, and standard payment gateways). This feature enables sequential refunds when a single payment method has insufficient balance.

---

✨ New Features

1. Split Refund Workflow

When refunding via gift card or voucher with insufficient balance:

• System displays an interactive dialog showing available balance vs. requested amount
• User can adjust products/quantities to fit within available balance
• After first refund, system prompts for remaining amount with alternative payment methods
• Process continues until full refund is completed or cancelled

2. Gift Card & Voucher Tracking

• Real-time display of remaining refundable amounts for promotional payments
• Visual indicators (✅) when promotional methods are fully refunded
• Automatic calculation of used amounts from order history
• Refund summary shows promotional payment details

3. Stock Reintegration Control

• Admin can choose whether to reintegrate stock when refunding
• Default behavior: stock is reintegrated to original warehouse
• Clear UI explanation of the selected option
• Radio buttons for intuitive selection

4. Smart Method Availability

System automatically filters available refund methods based on:

• Payment method used for the original order
• Promotional payment status (gift card/voucher fully refunded or not)
• Remaining amounts per method
• Business rules enforcement

5. Enhanced Validations

• Gift cards must be fully refunded before vouchers
• Both promotional methods must be fully refunded before using PayPlug/PayPal/Credit Card
• Amount limits per method are enforced
• Clear error messages guide the user through valid operations

---

🔄 Refund Priority Flow

Priority Order:

1. Gift Card (if used)
2. Voucher (if used, and gift card is fully refunded)
3. Payment Gateway (PayPlug/PayPal/Credit Card) - only after promotional methods are cleared
4. Manual - always available

---

🎨 User Interface Improvements

Refund Summary Section

• Displays promotional payments with remaining amounts
• Visual indicators for completed refunds
• Real-time calculation updates

Split Dialogs

• Insufficient Balance Dialog: Adjust products/quantities to fit available amount
• Remaining Amount Dialog: Select method and products for remaining balance
• Success Dialog: Confirmation when all refunds are processed
• Interactive product selection with quantity controls
• Live total calculations with validation

Method Selector Dropdown

• Dynamically filtered based on context
• Displays remaining amounts for promotional methods
• Disabled options when conditions aren't met

---

🧪 Scenarios Covered

Note: These are examples among possible cases

Scenario 1: Partial Gift Card Refund

• Order: 150€ (Gift Card: 100€, PayPal: 50€)
• Refund request: 120€ via Gift Card
• Result: System refunds 100€ via GC, prompts for remaining 20€ via alternative method

Scenario 2: Full Promotional Refund

• Order: 200€ (GC: 80€, Voucher: 70€, PayPal: 50€)
• Refund sequence:
  1. GC: 80€ ✅
  2. Voucher: 70€ ✅
  3. PayPal now available for remaining 50€

Scenario 3: Stock Control

• Admin can choose to exclude returned items from stock reintegration
• Useful for damaged/non-resellable products

---

🔍 Business Rules Enforced

✅ Gift card must be refunded before voucher
✅ Promotional payments cleared before gateway refunds
✅ Maximum refund per method cannot exceed original payment
✅ Total refunds cannot exceed order total
✅ Manual method always available as fallback

---

Related Ticket: MS-170