[MinePay] Top Donator placeholder support added.

MinePay now registers placeholders with PlaceholderAPI (if installed),
allowing you to display live top donator data in holograms, scoreboards,
tab lists, and any other PAPI-compatible plugin.

PlaceholderAPI is optional, MinePay works normally without it.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LEADERBOARD PLACEHOLDERS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
-- Replace <n> with the position (1, 2, 3, etc.)

Monthly:
%minepay_monthly_name_<n>% Top donor name
%minepay_monthly_amount_<n>% Total donated (e.g. 25.00)
%minepay_monthly_count_<n>% Number of purchases
%minepay_monthly_lastdonation_<n>% Last donation date
%minepay_monthly_period% Current period (e.g. May 2026)

All-Time:
%minepay_alltime_name_<n>%
%minepay_alltime_amount_<n>%
%minepay_alltime_count_<n>%
%minepay_alltime_lastdonation_<n>%
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PLAYER SELF PLACEHOLDERS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
-- These reflect the stats of whichever player is viewing the text.

%minepay_monthly_rank% Your monthly rank (or "Unranked")
%minepay_monthly_donated% Your monthly total donated
%minepay_monthly_count% Your monthly purchase count

%minepay_alltime_rank%
%minepay_alltime_donated%
%minepay_alltime_count%
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE HOLOGRAM LINES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
&6&l#1 &f%minepay_monthly_name_1% &8- &a$%minepay_monthly_amount_1%
&e&l#2 &f%minepay_monthly_name_2% &8- &a$%minepay_monthly_amount_2%
&c&l#3 &f%minepay_monthly_name_3% &8- &a$%minepay_monthly_amount_3%
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NOTES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Data is cached and refreshed every 30 minutes automatically.
• If a slot is empty (e.g. fewer than 10 donors this month),
the placeholder returns blank rather than an error.
• Requires PlaceholderAPI to be installed on the server.
MinePay functions normally if it is not present.

MinePay Update
==============

Bug Fixes
---------
- Gift cards UI producing errors -> Fixed an error that occurred when loading gift card data in server builds. Gift cards now load correctly every time.
- Gift card data corrupting after build -> Player gift card files (balance, notes, etc.) were losing their field names after the server would restart and build again. Added protection rules to keep that data intact.

Improvements
------------
- Purchase requirements are now fully translatable -> Every message shown when a player does or doesn't meet a shop item's requirements can now be customized in Locales.yml. This includes pass/fail indicators, error messages, and requirement type labels.
- Gift Card Selection GUI is now fully translatable -> Item names, balance info, pagination buttons, the summary panel, and confirm/clear buttons all pull from Locales.yml.
- Gift Card Creation GUI is now fully translatable -> Player head hints, the info item, amount/note buttons, the create button, and all chat feedback messages now pull from Locales.yml.

New Locale Keys
---------------
Add any of the following to your Locales.yml to customize the new strings.
All defaults are shown. If a key is missing, the default will be used automatically.

# Gift Card Selection GUI
giftcard_item_title: '&a&lGift Card #{id}'
giftcard_item_balance: '&eBalance: &a{balance}'
giftcard_item_original: '&7Original: {balance}'
giftcard_item_created: '&7Created: &f{date}'
giftcard_item_from: '&7From: &f{player}'
giftcard_item_note: '&7Note: &f{note}'
giftcard_item_selected: '&a✓ SELECTED'
giftcard_item_click_deselect: '&7Click to deselect'
giftcard_item_click_select: '&7Click to select'
giftcard_prev_page: '&e« Previous Page'
giftcard_prev_page_hint: '&7Click to go to previous page'
giftcard_next_page: '&eNext Page »'
giftcard_next_page_hint: '&7Click to go to next page'
giftcard_info_total: '&eOrder Total: &f{amount}'
giftcard_info_applied: '&eGift Cards: &a-{amount}'
giftcard_info_remaining: '&6Remaining: &f{amount}'
giftcard_info_count: '&7Selected Cards: &f{count}'
giftcard_info_ids_header: '&7Selected IDs:'
giftcard_info_id_entry: '&a• #{id} &7({balance})'
giftcard_confirm_selection: '&a&lConfirm Selection'
giftcard_confirm_hint1: '&7Click to confirm selection'
giftcard_confirm_hint2: '&7and return to checkout'
giftcard_clear_selection: '&c&lClear Selection'
giftcard_clear_hint1: '&7Click to clear all selected'
giftcard_clear_hint2: '&7gift cards'

# Gift Card Creation GUI
giftcard_create_info_title: '&b&lCreate Gift Card'
giftcard_create_select_hint1: '&7Click to select this player'
giftcard_create_select_hint2: '&7to receive a gift card'
giftcard_create_player_selected: '&a✓ SELECTED'
giftcard_create_info_hint1: '&7Select a player to give'
giftcard_create_info_hint2: '&7a gift card to.'
giftcard_create_info_online: '&7Online Players: &f{count}'
giftcard_create_enter_name_button: '&e&lEnter Player Name'
giftcard_create_enter_name_hint1: '&7Click to enter a player name'
giftcard_create_enter_name_hint2: '&7if they are not online'
giftcard_create_selected_title: '&a&lSelected: &e{player}'
giftcard_create_selected_amount: '&7Amount: &a{amount}'
giftcard_create_selected_note: '&7Note: &f{note}'
giftcard_create_selected_deselect: '&7Click to deselect'
giftcard_create_amount_selected: '&a✓ Selected'
giftcard_create_amount_select: '&7Click to select'
giftcard_create_custom_amount_title: '&6&lCustom Amount'
giftcard_create_custom_amount_current: '&7Current: &a{amount}'
giftcard_create_custom_amount_hint: '&7Click to enter custom amount'
giftcard_create_note_title: '&e&lAdd Note'
giftcard_create_note_none: '&7No note set'
giftcard_create_note_current: '&7Current: &f{note}'
giftcard_create_note_hint: '&7Click to add/edit note'
giftcard_create_button_title: '&a&lCreate Gift Card'
giftcard_create_button_player: '&7Player: &e{player}'
giftcard_create_button_amount: '&7Amount: &a{amount}'
giftcard_create_button_note: '&7Note: &f{note}'
giftcard_create_button_click: '&aClick to create gift card!'
giftcard_create_amount_set: '&aAmount set to: &e{amount}'
giftcard_create_amount_invalid: '&cAmount must be greater than 0'
giftcard_create_invalid_number: '&cInvalid number: {input}'
giftcard_create_note_set: '&aNote set: &7{note}'
giftcard_create_no_player: '&cPlease select a player first!'
giftcard_create_player_selected_msg: '&aSelected player: &e{player}'
giftcard_create_player_not_found: '&cPlayer ''{player}'' has never joined this server!'

# Purchase Requirements
requirement_met: '&a✓ {placeholder}: {value}'
requirement_not_met: '&c✗ {message} &7({type}, Have: {value})'
requirement_placeholderapi_missing: '&c✗ {message} &7(PlaceholderAPI not installed)'
requirement_placeholder_not_found: '&c✗ {message} &7(Placeholder ''{placeholder}'' not found)'
requirement_invalid_number: '&c✗ {message} &7(Invalid number comparison)'
requirement_invalid_type: '&c✗ {message} &7(Invalid requirement: missing comparison type)'
requirement_type_equals: 'Need: {value}'
requirement_type_not_equals: 'Must not be: {value}'
requirement_type_contains: 'Must contain: {value}'
requirement_type_greater_than: 'Need > {value}'
requirement_type_less_than: 'Need < {value}'

---
## New Features

### Gift Card System Integration
- **Gift cards now apply discounts at checkout** - Selected gift cards properly reduce the PayPal order amount
- Gift cards are automatically consumed when payment completes successfully
- Supports both single item purchases and cart orders
- If gift cards fully cover the order cost, items are delivered instantly without requiring PayPal payment

### `/giftcards` Command
- New standalone command for players to view their gift cards
- Displays all active gift cards with balance, original amount, and creation info
- Paginated GUI with material indicators based on balance tier:
- $50+: Emerald
- $20+: Diamond
- $10+: Gold Ingot
- $5+: Iron Ingot
- Under $5: Brick
- Aliases: `/gc`, `/mygiftcards`

### Admin Gift Card Commands

#### `/minepay give <player> <category> <item> [amount]`
- Give shop items directly to players without payment
- Full tab completion for players, categories, and items
- Requires `minepay.give` permission

#### `/minepay giftcard`
- Opens admin GUI for creating gift cards
- Select recipient from online players or enter offline player name
- Customizable amount with preset buttons (1/8/16/32/64 stack indicators)
- Optional note field for personalization
- Recipients see notification from "Staff"
- Requires `minepay.admin or minepay.giftcard` permission

### Dashboard Gift Card Display
- Transaction details now show gift card discount amount when applicable
- Green "Gift Card Applied" banner in transaction drawer
- Amount column shows discount chip with tooltip in transactions table

### Bug Fixes
- Fixed an issue where back buttons and close buttons on the GUI's would sometimes visually allow you to grab them, but not be placeable and non-existent as a sort of "Ghost" block/item.

- Fixed pagination buttons appearing when not needed - Previous/Next page buttons in gift card GUIs now only display when there are actually multiple pages of content.

- Fixed QR code preference not being preserved during async order creation - The QR code toggle setting is now maintained throughout the entire checkout flow.

- Fixed variable selection price additions persisting after failed purchases - Variable price modifiers are now properly cleared when a purchase fails due to unmet requirements.

### New Locales
```
# Gift Cards
giftcard_selection_title: '&d&lSelect Gift Cards'
giftcard_summary_name: '&b&lGift Card Summary'
giftcard_button_name: '&d&lGift Cards'
giftcard_button_lore1: '&7Apply gift cards to'
giftcard_button_lore2: '&7reduce your total'
giftcard_button_available: '&aYou have {count} gift card(s) available!'
giftcard_button_none: '&7No gift cards available'
giftcard_selected: '&aGift card #{id} selected! ({amount})'
giftcard_deselected: '&7Gift card #{id} deselected'
giftcard_selection_cleared: '&7All gift cards deselected'
giftcard_applied: '&aGift cards applied! ({amount} discount)'
```

```
# Give Command
give_success: '&aSuccessfully gave &e{amount}x {item} &ato &e{player}&a!'
give_received: '&aYou received &e{amount}x {item} &afrom an admin!'

# Gift Card Creation
giftcard_creation_title: '&d&lCreate Gift Card'
giftcard_enter_player_prompt: 'Enter Player Name'
giftcard_enter_player_placeholder: 'Type the player name'
giftcard_enter_amount_prompt: 'Enter Gift Card Amount'
giftcard_enter_amount_placeholder: 'Type the amount (e.g. 25.00)'
giftcard_enter_note_prompt: 'Enter Gift Card Note'
giftcard_enter_note_placeholder: 'Type a note (optional)'
giftcard_created_success: '&aGift card #&e{id}&a created for &e{player}&a with &e{amount}&a!'
giftcard_received_notification: '&aYou received a &e{amount}&a gift card from &e{from}&a!'
```
---

Configurable No-Requirement Sound

• Added no_requirement_sound configuration option in Shop.yml
• Allows server owners to customize the sound played when players don't meet item requirements
• Default: ENTITY_VILLAGER_NO with automatic fallback to VILLAGER_NO for MC 1.8 compatibility
• Set to empty string ('') or 'none' to disable the sound
• Examples: 'ENTITY_ENDERMAN_TELEPORT', 'BLOCK_NOTE_BLOCK_BASS', 'UI_BUTTON_CLICK'

New Locale Changes for tooltip price displays
price_discounted: '&aPrice: &e{price} &c&l{discount}'
price_base: '&7Base Price: &e{price}'
price_variables: '&7Variables: &e+{price}'
price_total: '&7Total: &a{price}'
price_total_discounted: '&7Total: &a{price} &c&l{discount}'
price_total_label: '&7Total Price: &a{price}'
Clear Cart Button Configuration

• Added clear_cart button configuration to confirmation GUI in Shop.yml
• Fully customizable with material, display name, and lore
• Includes placeholders: {cart_count} and {cart_total}
• Default slot: 18

Changes
Configuration Files
Shop.yml now includes:

# Sound played when player doesn't meet requirements for an item
no_requirement_sound: 'ENTITY_VILLAGER_NO'

gui:
confirmation:
clear_cart:
enabled: true
slot: 18
material: BARRIER
display_name: '&c&lClear Cart'
lore:
- ''
- '&eCart Items: &f{cart_count}'
- '&eCart Total: &a{cart_total}'
- ''
- '&7Click to clear your cart'
- '&7and close this menu'
- ''
- '&c&lWarning: This cannot be undone!'

## Version [V1.0.0.8] - January 7, 2026

### New Features

#### Top Donators Leaderboard System
- **Added `/topdonators` command** - Display comprehensive donation leaderboards for your server
- View top 50 donors with customizable time periods (monthly/all-time)
- Command aliases: `/topdonos`, `/topdonators`
- Beautifully formatted GUI showing donor rankings, amounts, and statistics
- Helps recognize and reward your most generous community supporters

#### Version Information Command
- **Added `/minepay version` command** - Check your current MinePay installation version
- Displays current version number and build information
- Quick verification to ensure you're running the latest release
- Useful for troubleshooting and support requests

#### Critical Update Notification System
- **Introduced automatic update alerts** - Stay informed about mandatory updates
- Real-time notifications when critical updates are available
- Alerts server operators/administrators about important MinePay patches and breaking changes
- Displays update priority level (optional, recommended, critical, mandatory)

### Improvements

#### Simplified Setup & Configuration
- **Removed server port webhook requirement** - Setup process is now dramatically easier
- No more port forwarding configuration needed
- No firewall rule modifications required
- Eliminated complex network setup for non-technical server owners
- Reduced the time between setup and finally being able to accept payments from 10+ minutes anywhere to under 2 minutes

### Website & Platform Updates

#### Enhanced Wiki Documentation
- **Completely redesigned wiki interface** - Modern, searchable documentation hub
- Troubleshooting section covering common issues and solutions

#### Streamlined Server Creation & Linking
- **Improved server registration flow** - Create and link servers in seconds
- Bulk server management for networks with multiple servers
- Removed port-related options when adding/creating a new server via the Trinetic website.

### Technical Improvements

- Migrated from port-based webhooks to new a new plug-and-play system requiring little to no setup.
- Website performance optimizations.

### Notes

- Existing webhook configurations will automatically migrate - no manual action required
- The new system works seamlessly with all server hosting providers
- Port forwarding settings can be safely removed from your router/firewall/hosting provider dashboard
- Top donors are cached and refreshed between intervals for optimal performance
- Visit the new wiki at [trinetic.net/wiki]( https://trinetic.net/wiki) for complete documentation
- Existing server configurations remain unchanged and fully compatible

New Features
QR Code Support for Payment Links

• Added QR Code toggle in confirmation GUI - Players can now choose to receive PayPal payment links as QR code images on maps
• Bottom-right placement - QR code toggle button positioned at slot 26 for easy access
• Bedrock player support - QR codes enable Bedrock Edition players to complete purchases, as they cannot click chat links
• Modern payment flow - Players can scan QR codes with their mobile devices to complete PayPal checkout seamlessly

Bug Fixes
PayPal Integration

• Fixed AMOUNT_MISMATCH error - Resolved PayPal order creation failures caused by rounding discrepancies
  • Unit price calculation now properly accounts for decimal precision
  • Ensures unit_price × quantity exactly matches item_total to pass required user validation
  • Prevents order failures when selecting quantities in the ItemQuantityGUI

QR Code Generation

• Corrected context lifecycle management to preserve QR code preference during async PayPal API calls
• Added proper context cleanup after successful order creation, errors, and sandbox mode
• Context is now maintained throughout the entire order flow instead of being removed prematurely

Technical Improvements

• Enhanced debug logging for item amount calculations
• Improved error handling with proper context cleanup in all failure scenarios
• Added validation logging to track unit price × quantity matching
• Optimized context removal timing across confirm, decline, and cart clear actions

Notes

• QR code maps are automatically added to player inventory when the feature is enabled
• QR Code maps are automatically removed on right click/after 10 minutes of not being used.
• Both standard clickable links and QR codes are provided for maximum compatibility
• Sandbox mode properly cleans up context after simulation

Added

• Added the ability to set categories as Admin Only, requiring the minepay.admin permission to view.

Changed

• Updated port handling so if the configured port is already in use, MinePay will automatically overwrite the config with a new usable port.

Fixed

• Fixed multiple bugs related to the admin GUI.

Added / Changed

• Implemented a fallback error when the server is not connected or properly set up with PayPal.
• Updated Locales.yml to clean up PayPal order creation text.
• Updated the Trinetic Website to make the PayPal connection process more obvious and less intrusive during setup.

Added

• Added a version checker that notifies server operators when MinePay is outdated.
• Added full support for Minecraft versions 1.8.8 through 1.21.

Fixed

• Fixed multiple issues related to coupon codes.
• Fixed various general bugs and stability issues.
• Fixed an issue where category and item enchantment effects would sometimes not display correctly.

Notes
This update is strongly recommended for all servers, especially those using coupon codes or running newer Minecraft versions.

IMPORTANT
Added a non-destructive auto migration for the config files whenever development adds new fields to the files.
Your configs should remain left intact with the new fields at the very bottom.###

• Fixed bugs which were caused during checkout with multiple items from sub-menus
  
  
• Added coupons that can be configured via the discounts.yml
  
  
• Added The Ability To Enabled/Disable a sandbox_mode via the config.yml and use simulated transaction types
  

PAYMENT_SUCCESS
PAYMET_FAILED
PAYMENT_PENDING

# Sandbox mode for testing payments without real transactions
sandbox:
# Enable sandbox mode (uses test endpoint and simulates payment results)
enabled: false
# Simulation behavior: PAYMENT_SUCCESS or PAYMENT_FAILED
# PAYMENT_SUCCESS: Simulates a successful payment and executes commands
# PAYMENT_FAILED: Simulates a failed payment
simulate: PAYMENT_SUCCESS


coupons:
# Enable/disable the coupon system
enabled: true

# Coupon codes with advanced configuration
# Simple format: CODE: discount_percentage
# Advanced format:
# CODE:
# discount: percentage (0-100)
# categories:

• or "all" (default: "all")
  # stack: true/false (default: false)
  codes:
  # Simple format (applies to all categories, no stacking)
  WELCOME10: 10
  
  # Advanced format with category restrictions
  SUMMER25:
  discount: 25
  categories:
  - Weapons
  - Armor
  stack: false
  
  # VIP coupon with stacking enabled
  VIP50:
  discount: 50
  stack: true
  categories: all
  
  # Creator code applies to specific categories only
  CREATOR15:
  discount: 15
  categories:
  - Custom_Items
  - Discord_Ranks
  stack: true

- Added support for 1.20.1

- Added support for `show_price: false` to items inside of categories