> 💡 `_can_redeem` checks: code status normal, not expired, uses left, not locked by others, and current player hasn't redeemed it.

---

### Usage Notes

- **All monetary placeholders** are in `yuan`, with two decimal places, e.g. `99.50`. Integer amounts also show `.00`.
- Dynamic time parameter `` always uses **milliseconds** — 24h = `86400000`, 7d = `604800000`.
- Code strings in placeholders are auto-uppercased; lowercase input works too.
- Server and leaderboard placeholders **do not require a player context**; personal and some code placeholders **require a player** or return empty/default.
- Placeholders work in any plugin that supports PlaceholderAPI (scoreboard, BossBar, DeluxeTags, chat prefix, item lore, etc.).

---

## 🧩 Gift for Developers

If you can write plugins, these events will make your secondary development experience fly:

| Event | Trigger | Modifiable Parameters |
|-------|---------|----------------------|
| `PrePaymentEvent` | Before payment | amount, payment method, order ID, cancel flag |
| `PaymentOrderCreatedEvent` | Order created successfully | read-only (has QR URL) |
| `PaymentCompletedEvent` | Payment success + rewards granted | read-only (full data) |
| `PaymentFailedEvent` | Payment failed / canceled | read-only |
| `RefundCompletedEvent` | Refund completed | read-only |
| `RedeemCodeRedeemedEvent` | Code redeemed | read-only |
| `RedeemCodeLifetimeEvent` | Code status changed | read-only (old → new state) |
| `PlayerPointsChangedEvent` | Economy changed | read-only |

All events support sync. You can intercept before order creation, trigger联动 other systems after payment, sync data on refund — every detail of the sponsorship lifecycle is observable.

---

## 🛡️ Security Is Not Just Talk

- **Signature verification**: WeChat/Alipay callbacks are fully signature-verified against forgery
- **Anti-duplicate delivery**: Order status check + idempotent handling
- **IP whitelist**: Callback interface can restrict access to official payment platform IPs only
- **TLS/HTTPS**: Supports certificate-encrypted communication
- **Event monitoring**: `/yp audit` one-click audit, 24h monitoring of which plugins are listening to YuPay's fund events
- **Map virtual lock**: When a payment QR is placed in the inventory, the player is locked in place, cannot drop/switch items, payment unlocks

---

## ⚡ Blazing Fast Startup

The rewritten dependency loading system means YuPay no longer requires cumbersome JVM startup parameters. All dependencies are automatically managed, verification speed increased by 600%, out-of-the-box. Drop it into the `plugins` folder, start the server, it's ready.

---

## 📊 Data at Your Fingertips

`/yp history` is one of your most-used commands. Order history supports **page browsing**, click an order ID to **copy it with one click** — reconciliation efficiency doubled.

`/yp top` lets you know at any time who is contributing to the server — leaderboard data syncs with placeholders in real time.

`/yp total` for personal stats, `/yp total all` for server-wide stats — all available at your fingertips.

---

## 🚀 Two-Minute Quick Start Guide

1. Drop `YuPay.jar` into the `plugins/` folder
2. Start the server, wait for `config.yml` and `messages.yml` to generate
3. Open `config.yml`, fill in your WeChat/Alipay parameters
4. Ensure the callback port (default `8080`) is open in your server firewall and security group
5. In-game, type `/donate 0.01` to test a small payment
6. Confirm callback works and rewards arrive — start business 🎉

---

## 🏆 Why Server Owners Are Using YuPay

- ✅ **Stable**: Production-tested, compatible with Spigot/Paper 1.8 to latest versions
- ✅ **Reliable**: Direct official API connection, no middlemen, money goes to your account directly
- ✅ **Worry-free**: From payment to rewards fully automated, you just configure
- ✅ **Flexible**: Reward logic fully programmable, command aliases freely definable
- ✅ **Secure**: Signature verification + anti-duplicate + IP whitelist + event monitoring
- ✅ **Transparent**: Every order, every refund, every code redemption has logs
- ✅ **Evolving**: Actively maintained, continuously iterated, community-driven

---

> 💬 **Plugin Discussion Group: 1080918424**
>
> For issues, feature requests, or just to chat — welcome. Every improvement of YuPay comes from feedback from server owners.

> 💛 **Support the Author on AiFaDian**: https://ifdian.net/item/012b6c1c4a0911f18d1b52540025c377
>
> If YuPay has helped your server, consider buying the author a milk tea ~ Your support is the biggest motivation for the plugin's continued evolution.

**Stop struggling with sponsorship management. Leave the professional stuff to YuPay, and focus on running your server well.**

***

# 📖 YuPay Operation Manual

## 1. Environment Requirements

| Item | Requirement |
|------|-------------|
| Server | Spigot / Paper / compatible forks / compatible hybrid servers, 1.8 – 1.26+ |
| Java | JDK 8 or higher |
| Optional dependencies | Vault (economy), PlayerPoints (points), PlaceholderAPI (placeholders), ProtocolLib (map lock) |

> 🎉 **Good news**: You no longer need to manually add JVM startup parameters for Java 9+. YuPay's latest version has built-in smart dependency management — out-of-the-box.

## 2. Installation & Startup

1. Download `YuPay.jar`, place it in the server's `plugins/` directory
2. Start the server, the plugin will automatically generate `config.yml`, `messages.yml`, and SQLite database files
3. Edit `plugins/YuPay/config.yml`, fill in payment channel configuration parameters
4. Depending on your payment method, configure callback URLs in the payment platform backend:
- WeChat: `http(s)://your-domain-or-ip:port/pay/wechat/notify`
- Alipay: `http(s)://your-domain-or-ip:port/pay/alipay/notify`
5. Ensure the callback port (default `8080`) is open in firewall and security group
6. Execute `/yupay reload` or type `reload` in console to apply configuration
7. In-game, type `/donate 0.01` to test a small payment

## 3. Configuration Quick Reference

### 3.1 Core Payment Parameters

| Path | Description | Example |
|------|-------------|---------|
| `pay.default-method` | Default payment method | `wechat` / `alipay` |
| `pay.min-amount` | Minimum amount per order (yuan) | `0.01` |
| `pay.max-amount` | Maximum amount per order (-1 = unlimited) | `500` |
| `pay.max-daily-amount` | Daily cumulative limit (-1 = unlimited) | `1000` |
| `pay.order-subject` | Order subject template | `Sponsorship-{player}-{amount}yuan` |

### 3.2 WeChat Pay Parameters

| Path | Description |
|------|-------------|
| `wechat.enabled` | Enable (true/false) |
| `wechat.mchid` | Merchant ID |
| `wechat.appid` | Official account / Mini Program AppID |
| `wechat.serial-no` | API certificate serial number |
| `wechat.private-key-path` | Merchant private key (relative to `pems/` directory) |
| `wechat.public-key-path` | Platform public key (relative to `pems/` directory) |
| `wechat.public-key-id` | Platform public key ID |
| `wechat.api-v3-key` | API v3 key (32 characters) |
| `wechat.notify-url` | Complete callback notification URL |

### 3.3 Alipay Parameters

| Path | Description |
|------|-------------|
| `alipay.enabled` | Enable |
| `alipay.mode` | `public_key` or `cert` |
| `alipay.app-id` | App ID |
| `alipay.merchant-private-key` | Merchant private key (PKCS8, without headers/footers) |
| `alipay.alipay-public-key` | Alipay public key (required for public_key mode) |
| `alipay.app-cert-path` | App public key certificate (cert mode) |
| `alipay.alipay-cert-path` | Alipay public key certificate (cert mode) |
| `alipay.alipay-root-cert-path` | Alipay root certificate (cert mode) |
| `alipay.notify-url` | Async notification URL |
| `alipay.return-url` | Sync return URL |

### 3.4 Economy System

| Path | Description |
|------|-------------|
| `economy.enabled` | Enable economy rewards |
| `economy.type` | `vault` or `playerpoints` |
| `economy.rate` | 1 yuan = how many in-game currency/points |

### 3.5 QR Code Display

| Path | Description |
|------|-------------|
| `qrcode.default-output-mode` | `link` / `text` / `map` |
| `qrcode.text-qr-size` | Text mode QR side length (characters, default 12) |
| `qrcode.text-black-char` | Black pixel character (default `██`) |
| `qrcode.api-url` | Image generation API for link mode |

### 3.6 Callback Server

| Path | Description |
|------|-------------|
| `callback.port` | Listening port |
| `callback.host` | Bind address (`0.0.0.0` = all interfaces) |
| `callback.io-threads` | IO thread count |
| `callback.worker-threads` | Worker thread count |
| `callback.allowed-ips` | IP whitelist (CIDR format, empty = allow all) |
| `callback.access-log` | Enable access logging |

### 3.7 Database

| Path | Description |
|------|-------------|
| `database.type` | `sqlite` (standalone) or `mysql` (multi-server sync) |
| `database.mysql.*` | MySQL connection parameters |
| `database.connection-pool.*` | HikariCP connection pool parameters |
| `database.table-names.prefix` | Table prefix to avoid conflicts |
| `database.table-names.*` | Individual business table names (can be customized) |

## 4. Complete Reward Configuration Guide

### 4.1 Base Reward (on-success)

Executed on every successful payment — suitable for "base reward every sponsorship".

```yaml
commands:
on-success:
- "give {player} diamond 1"
- "effect give {player} minecraft:speed 30 1"
```

Available variables: `{player}` (player name), `{amount}` (amount), `{points}` (economy points earned)

### 4.2 Single Milestone (on-single-achieved)

Triggered when a single payment reaches a set amount. **Sort amounts from low to high**, multiple tiers allowed.

```yaml
commands:
on-single-achieved:
- amount: 50
commands:
- "say {player} reached 50 yuan in a single sponsorship!"
- "give {player} minecraft:gold_block 5"
- amount: 100
commands:
- "give {player} minecraft:diamond_block 3"
- "lp user {player} parent set vip"
```

### 4.3 Total Achievement (on-total-achieved)

Triggered when lifetime total reaches a new height. **Each tier triggers only once** — anti-duplicate mechanism built-in.

```yaml
commands:
on-total-achieved:
- total: 100
commands:
- "lp user {player} parent set vip"
- total: 1000
commands:
- "lp user {player} parent set ultimate"
- "give {player} minecraft:beacon 1"
```

### 4.4 Limited Sprint Reward (on-recent-achieved)

Triggered when cumulative amount within a specified time period (milliseconds) reaches the target. Great for holiday events, weekend leaderboard pushes, etc.

```yaml
commands:
on-recent-achieved:
- time: 86400000 # 24 hours
total: 200
commands:
- "give {player} minecraft:enchanted_golden_apple 5"
- time: 604800000 # 7 days
total: 500
commands:
- "give {player} minecraft:elytra 1"
```

### 4.5 Refund Trigger Commands (on-refund)

Executed after a successful refund — can be used to notify admins, log events.

```yaml
commands:
on-refund:
- "say {player}'s order {order} has been refunded {amount} yuan"
```

## 5. Command System

### 5.1 Player Commands

| Command | Function | Default Aliases |
|---------|----------|----------------|
| `/donate [payment] [output] [-n]` | Initiate sponsorship | `/pay`, `/zanzhu` |
| `/ytop` | Sponsorship leaderboard Top10 | `/paytop`, `/yt` |
| `/ytotal [player|all]` | Query total sponsorship | `/paytotal`, `/ytt` |
| `/yp history [page]` | My sponsorship history | `/yupay history` |
| `/yp lang [language]` | Switch personal language preference | |
| `/yp code redeem ` | Redeem a code | |
| `/yp cancel` | Cancel current map payment | |