# Giftcard Module Implementation
## Overview
A comprehensive giftcard system for Zapazime that allows businesses to sell giftcards, customers to redeem them for bookings, and tracks 14-day payouts to businesses.
## Features Implemented
### 1. Database Schema
- **giftcards table**: Stores giftcard templates/offers created by businesses
- Fields: company_id, code, name, description, amount, currency, valid_from, valid_until, max_uses, current_uses, is_active, image_path, terms_conditions, sort_order
- **giftcard_purchases table**: Tracks giftcard purchases by customers
- Added fields: client_id, balance_remaining, expires_at
- **giftcard_redemptions table**: Tracks when giftcards are used for bookings
- Fields: giftcard_purchase_id, booking_id, company_id, amount_used, currency, redeemed_by, redeemed_at, notes
- **giftcard_payouts table**: Tracks 14-day payouts to businesses
- Fields: company_id, giftcard_purchase_id, amount, currency, payout_status, purchase_date, scheduled_payout_date, paid_at, transaction_reference, notes, metadata
- **companies table**: Added accepts_giftcards field for business opt-in
### 2. Models Created
- **Giftcard**: Model for giftcard templates with relationships to company and purchases
- **GiftCardPurchase**: Updated model with redemption and payout support, balance tracking
- **GiftcardRedemption**: Model for tracking giftcard usage on bookings
- **GiftcardPayout**: Model for managing 14-day business payouts
### 3. Filament Admin Resources
- **GiftcardResource**: Manage giftcard templates (create, edit, view, delete)
- **GiftcardPurchaseResource**: View and manage giftcard purchases with relation managers for redemptions and payouts
- **GiftcardPayoutResource**: Manage and process 14-day payouts with status tracking
### 4. Business Settings
- Added `accepts_giftcards` toggle to Company form and table
- Businesses can explicitly choose whether to accept giftcards as payment method
- Filter added to Company table to filter by giftcard acceptance
### 5. Services
- **GiftcardService**: Core business logic for giftcard operations
- validateGiftcardCode(): Validate giftcard codes
- redeemGiftcard(): Redeem giftcard for booking
- getUserGiftcards(): Get user's available giftcards
- getGiftcardBalance(): Check remaining balance
- companyAcceptsGiftcards(): Check if business accepts giftcards
- getMaxRedeemableAmount(): Calculate maximum redeemable amount
- refundRedemption(): Refund giftcard redemption
### 6. 14-Day Payout System
- **ProcessGiftcardPayouts Command**: Console command to process due payouts
- Automatically runs to find payouts due for payment (14 days after purchase)
- Checks company bank details before processing
- Marks payouts as scheduled/completed/failed
- Logs all payout activities
- Command: `php artisan giftcards:process-payouts`
### 7. Translations
Added giftcard-related translations to all supported languages:
- English (en.json)
- Bulgarian (bg.json)
- German (de.json)
- Greek (el.json)
- Spanish (es.json)
- French (fr.json)
- Italian (it.json)
- Polish (pl.json)
- Romanian (ro.json)
- Russian (ru.json)
- Turkish (tr.json)
Translation keys added:
- Gift Cards
- Gift Card
- Gift Card Purchases
- Gift Card Purchase
- Gift Card Payouts
- Gift Card Payout
- Accept Gift Cards
## Database Migrations
1. `2026_08_31_140000_create_giftcards_table.php` - Creates giftcards, giftcard_purchases, giftcard_redemptions, giftcard_payouts tables
2. `2026_08_31_141000_add_giftcard_columns_to_gift_card_purchases.php` - Adds client_id, balance_remaining, expires_at to existing gift_card_purchases table
3. `2026_08_31_142000_add_giftcard_acceptance_to_companies.php` - Adds accepts_giftcards field to companies table
## File Structure
```
app/
├── Models/
│ ├── Giftcard.php
│ ├── GiftCardPurchase.php (updated)
│ ├── GiftcardRedemption.php
│ ├── GiftcardPayout.php
│ └── Company.php (updated)
├── Services/
│ └── GiftcardService.php
├── Console/Commands/
│ └── ProcessGiftcardPayouts.php
├── Filament/
│ ├── Resources/
│ │ ├── GiftcardResource.php
│ │ ├── GiftcardResource/Pages/
│ │ ├── GiftcardPurchaseResource.php
│ │ ├── GiftcardPurchaseResource/Pages/
│ │ ├── GiftcardPurchaseResource/RelationManagers/
│ │ ├── GiftcardPayoutResource.php
│ │ └── GiftcardPayoutResource/Pages/
│ └── Components/
│ ├── Forms/CompanyFormNew.php (updated)
│ └── Tables/CompanyTable.php (updated)
database/
└── migrations/
├── 2026_08_31_140000_create_giftcards_table.php
├── 2026_08_31_141000_add_giftcard_columns_to_gift_card_purchases.php
└── 2026_08_31_142000_add_giftcard_acceptance_to_companies.php
resources/
└── lang/
├── en.json (updated)
├── bg.json (updated)
├── de.json (updated)
├── el.json (updated)
├── es.json (updated)
├── fr.json (updated)
├── it.json (updated)
├── pl.json (updated)
├── ro.json (updated)
├── ru.json (updated)
└── tr.json (updated)
```
## Usage
### For Businesses
1. Enable "Accept Gift Cards" in company settings
2. Create giftcard templates via Filament admin panel
3. Set amount, validity period, and terms
4. Manage giftcard purchases and view redemptions
5. Process 14-day payouts to businesses
### For Customers
1. Purchase giftcards via existing checkout flow
2. Receive unique purchase code
3. Redeem giftcards during booking checkout
4. Track remaining balance
5. Use partial or full balance across multiple bookings
### For Admin
1. Monitor all giftcard activity
2. View redemption history
3. Track pending and completed payouts
4. Process scheduled payouts via command
5. Filter and export reports
## Integration Points
### Booking Payment Flow
The GiftcardService can be integrated into the booking payment flow:
```php
$giftcardService = new GiftcardService();
$purchase = $giftcardService->validateGiftcardCode($code);
if ($purchase) {
$redemption = $giftcardService->redeemGiftcard($purchase, $booking, $amount);
}
```
### Scheduled Payouts
Add to cron schedule in `app/Console/Kernel.php`:
```php
$schedule->command('giftcards:process-payouts')->daily();
```
## Next Steps
1. Integrate giftcard redemption UI in booking checkout
2. Add giftcard validation API endpoints for mobile app
3. Implement actual banking integration for payouts
4. Add email notifications for giftcard purchases and redemptions
5. Create giftcard templates library for businesses
6. Add reporting and analytics for giftcard performance
## Notes
- Existing GiftCardPurchase model was extended rather than replaced to maintain backward compatibility
- Payout system is ready for banking integration (currently simulates transfers)
- All translations use underscore notation as per project guidelines
- Filament v4.12.5 compatibility maintained
- Company scope and workspace scope applied where appropriate