> For the complete documentation index, see [llms.txt](https://korapay.kingora.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://korapay.kingora.net/korapayments-wiki.md). # KoraPayments Wiki Tài liệu hướng dẫn sử dụng các placeholder dạng `%kp_...%` của plugin KoraPayments để hiển thị tổng nạp cá nhân, tổng nạp server, bảng xếp hạng nạp và tiến trình mốc nạp server trong scoreboard, TAB, menu, hologram hoặc các plugin hỗ trợ PlaceholderAPI. [Bắt đầu sử dụng](#setup) [Xem ví dụ cấu hình](#examples) ## Thông tin | Mục | Giá trị | | ------------------ | ----------------------------- | | Plugin | KoraPayments | | Expansion | kp | | Placeholder | `%kp_...%` | | Phiên bản tài liệu | 1.2.2+ | | Cập nhật | 2026-05-09 | | Author | DuyDuong | | Discord | lz.dy.dg | | Định danh | %`kp_%` | | Kiểu dữ liệu | Tổng nạp, top nạp, mốc server | | Định dạng tiền | `1,000,000` | ## Tổng quan KoraPayments đăng ký PlaceholderAPI expansion nội bộ với identifier `kp`. Vì vậy các placeholder sẽ có dạng `%kp_ten_placeholder%`. Không cần expansion eCloud riêng Người chơi ### Tổng nạp cá nhân Hiển thị số tiền người chơi đã nạp theo toàn thời gian, ngày, tuần, tháng hoặc năm. Server ### Tổng nạp toàn server Hiển thị tổng doanh thu đã ghi nhận trong database của KoraPayments. Top ### Bảng xếp hạng nạp Lấy tên và số tiền của người chơi ở từng hạng để đưa vào scoreboard hoặc menu. {% hint style="info" %} Placeholder chỉ có dữ liệu sau khi giao dịch nạp thẻ hoặc nạp bank được plugin ghi nhận thành công vào database. Nếu chưa có giao dịch, hầu hết placeholder số tiền sẽ trả về `0`. {% endhint %} ## Cài đặt và kiểm tra nhanh Làm theo các bước dưới đây để đảm bảo PlaceholderAPI hoạt động đúng với KoraPayments. {% stepper %} {% step %} #### Cài PlaceholderAPI Đặt PlaceholderAPI vào thư mục plugins, sau đó khởi động lại server. KoraPayments dùng softdepend, nên PlaceholderAPI cần được bật để expansion kp đăng ký. {% endstep %} {% step %} #### Cài KoraPayments Đặt file plugin KoraPayments vào thư mục plugins, cấu hình nạp thẻ và nạp bank, sau đó restart server để plugin tạo database và đăng ký placeholder. {% endstep %} {% step %} #### Kiểm tra bằng lệnh PAPI Dùng lệnh bên dưới trong console hoặc trong game để kiểm tra dữ liệu placeholder của chính bạn. ```bash /papi parse me %kp_donate_total% ``` Có thể thay `me` bằng tên người chơi nếu plugin hoặc phiên bản PlaceholderAPI bạn dùng hỗ trợ cú pháp đó. {% endstep %} {% endstepper %} ## Danh sách placeholder Tất cả placeholder hiện có của KoraPayments. Dùng ô tìm kiếm để lọc nhanh theo tên, nhóm hoặc công dụng. Prefix: `%kp_...%` | Placeholder | Nhóm | Kết quả trả về | Ví dụ hiển thị | | -------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------- | | `%kp_donate_total%` | Người chơi | Tổng số tiền người chơi đã nạp toàn thời gian. | 250,000 | | `%kp_donate_total_today%` | Người chơi | Tổng số tiền người chơi đã nạp trong ngày hiện tại. | 50,000 | | `%kp_donate_total_week%` | Người chơi | Tổng số tiền người chơi đã nạp trong tuần hiện tại. | 120,000 | | `%kp_donate_total_month%` | Người chơi | Tổng số tiền người chơi đã nạp trong tháng hiện tại. | 300,000 | | `%kp_donate_total_year%` | Người chơi | Tổng số tiền người chơi đã nạp trong năm hiện tại. | 1,250,000 | | `%kp_donate_server_total%` | Server | Tổng số tiền toàn server đã nạp, tính theo tất cả giao dịch đã lưu. | 15,750,000 | | `%kp_mocnapserver%` | Mốc nạp server | Tổng nạp toàn server dùng cho hệ thống mốc nạp server. | 15,750,000 | | `%kp_mocnapserver_total%` | Mốc nạp server | Giống `%kp_mocnapserver%`, trả về tổng nạp server. | 15,750,000 | | `%kp_mocnapserver_progress_1000000%` | Mốc nạp server | Tiến trình đạt mốc theo dạng đã đạt/mục tiêu. Nếu tổng nạp vượt mục tiêu, phần đã đạt được giới hạn bằng mục tiêu. | 750,000/1,000,000 | | `%kp_mocnapserver_percent_1000000%` | Mốc nạp server | Phần trăm hoàn thành mốc server, làm tròn và giới hạn từ 0 đến 100. | 75 | | `%kp_donate_total_top_player_1%` | Top nạp | Tên người chơi ở hạng 1 trong bảng xếp hạng nạp toàn thời gian. | Steve | | `%kp_donate_total_top_amount_1%` | Top nạp | Số tiền của người chơi ở hạng 1 trong bảng xếp hạng nạp toàn thời gian. | 2,000,000 | | `%kp_donate_total_top_player_1_today%` | Top nạp theo thời gian | Tên người chơi ở hạng 1 trong bảng xếp hạng nạp hôm nay. | Alex | | `%kp_donate_total_top_amount_1_today%` | Top nạp theo thời gian | Số tiền của hạng 1 trong bảng xếp hạng nạp hôm nay. | 100,000 | | `%kp_donate_total_top_player_1_week%` | Top nạp theo thời gian | Tên người chơi ở hạng 1 trong bảng xếp hạng nạp tuần hiện tại. | DuyDuong | | `%kp_donate_total_top_amount_1_week%` | Top nạp theo thời gian | Số tiền của hạng 1 trong bảng xếp hạng nạp tuần hiện tại. | 500,000 | | `%kp_donate_total_top_player_1_month%` | Top nạp theo thời gian | Tên người chơi ở hạng 1 trong bảng xếp hạng nạp tháng hiện tại. | Kingora | | `%kp_donate_total_top_amount_1_month%` | Top nạp theo thời gian | Số tiền của hạng 1 trong bảng xếp hạng nạp tháng hiện tại. | 1,500,000 | | `%kp_donate_total_top_player_1_year%` | Top nạp theo thời gian | Tên người chơi ở hạng 1 trong bảng xếp hạng nạp năm hiện tại. | Miner01 | | `%kp_donate_total_top_amount_1_year%` | Top nạp theo thời gian | Số tiền của hạng 1 trong bảng xếp hạng nạp năm hiện tại. | 8,500,000 | {% hint style="info" %} Với top nạp, thay số `1` bằng hạng mong muốn, ví dụ `2`, `3`, `10`. Rank phải là số nguyên lớn hơn `0`. {% endhint %} ## Quy tắc định dạng placeholder Nắm rõ các quy tắc dưới đây để tránh placeholder trả về sai hoặc không hiển thị. Top nạp ### Đúng thứ tự suffix thời gian Với top nạp theo ngày, tuần, tháng, năm, suffix thời gian phải đặt sau rank. ``` Đúng: %kp_donate_total_top_player_1_month% Đúng: %kp_donate_total_top_amount_3_week% Sai : %kp_donate_total_month_top_player_1% ``` Target ### Cách nhập mốc tiền Với placeholder mốc nạp server, phần target là số tiền mục tiêu. Plugin sẽ bỏ qua dấu phẩy, dấu chấm và dấu gạch dưới trong target. ``` %kp_mocnapserver_percent_1000000% %kp_mocnapserver_percent_1_000_000% %kp_mocnapserver_progress_5_000_000% ``` ### Giá trị trả về khi không có dữ liệu | Trường hợp | Giá trị trả về | Giải thích | | ------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------- | | Placeholder số tiền nhưng chưa có giao dịch | `0` | Database chưa có dữ liệu phù hợp với người chơi hoặc mốc thời gian. | | Top player không đủ hạng | `N/A` | Ví dụ server mới có 2 người nạp nhưng bạn gọi top player hạng 3. | | Top amount không đủ hạng | `0` | Không có người chơi ở hạng được yêu cầu nên số tiền trả về 0. | | Target mốc server không hợp lệ | `0` hoặc tổng nạp server | Percent trả về 0; progress trả về tổng nạp hiện tại nếu target nhỏ hơn hoặc bằng 0. | ## Ví dụ minh họa Các ví dụ dưới đây có thể chỉnh lại màu sắc và text theo phong cách server của bạn. ### 1. Test placeholder bằng lệnh Dùng lệnh này để xem tổng nạp cá nhân của người đang chạy lệnh. ```bash /papi parse me %kp_donate_total% ``` ### 2. Scoreboard hiển thị tổng nạp cá nhân Ví dụ dòng scoreboard đơn giản, phù hợp với các plugin scoreboard có hỗ trợ PlaceholderAPI. ``` &fBạn đã nạp: &a%kp_donate_total% VNĐ &fHôm nay: &e%kp_donate_total_today% VNĐ &fTháng này: &b%kp_donate_total_month% VNĐ ``` ### 3. Scoreboard top nạp tháng Hiển thị top 3 nạp tháng. Nếu chưa đủ người chơi, tên có thể hiện N/A và tiền có thể hiện 0. ``` &6Top nạp tháng &61. &f%kp_donate_total_top_player_1_month% &7- &a%kp_donate_total_top_amount_1_month% VNĐ &62. &f%kp_donate_total_top_player_2_month% &7- &a%kp_donate_total_top_amount_2_month% VNĐ &63. &f%kp_donate_total_top_player_3_month% &7- &a%kp_donate_total_top_amount_3_month% VNĐ ``` ### 4. DeluxeMenus hiển thị hồ sơ nạp Ví dụ item trong menu thông tin người chơi. ``` profile_donate: material: EMERALD slot: 13 display_name: '&aThông tin nạp' lore: - '&7Tổng đã nạp: &f%kp_donate_total% VNĐ' - '&7Hôm nay: &f%kp_donate_total_today% VNĐ' - '&7Tuần này: &f%kp_donate_total_week% VNĐ' - '&7Tháng này: &f%kp_donate_total_month% VNĐ' ``` ### 5. Mốc nạp server trong menu hoặc hologram Ví dụ hiển thị tiến trình đạt mốc 5,000,000 VNĐ cho toàn server. ``` &fMốc server: &a%kp_mocnapserver_progress_5_000_000% VNĐ &fTiến độ: &b%kp_mocnapserver_percent_5_000_000%% ``` ### 6. TAB hoặc NameTag hiển thị nạp tháng Dùng placeholder theo người chơi, phù hợp với TAB list hoặc profile hover text. ``` &7Nạp tháng: &e%kp_donate_total_month% VNĐ ``` ## Sửa lỗi thường gặp Một số lỗi phổ biến khi dùng placeholder trong scoreboard, TAB, menu hoặc hologram. Lỗi hiển thị ### Placeholder hiện nguyên dạng `%kp_...%` Thường do PlaceholderAPI chưa được cài, chưa bật, hoặc plugin hiển thị chưa bật hỗ trợ PlaceholderAPI. Hãy kiểm tra bằng `/papi parse me %kp_donate_total%`. Dữ liệu ### Placeholder luôn trả về `0` Kiểm tra xem người chơi đã có giao dịch thành công chưa, database có bị reset không, và plugin đang parse đúng context người chơi hay không. Top nạp ### Top player trả về `N/A` Rank được gọi chưa có dữ liệu. Ví dụ gọi hạng 10 nhưng server mới có 3 người từng nạp. Mốc server ### Phần trăm luôn là `100` Mục tiêu mốc đang nhỏ hơn hoặc bằng tổng nạp hiện tại. Hãy tăng target, ví dụ từ `1_000_000` lên `5_000_000`. {% hint style="warning" %} Sau khi thêm PlaceholderAPI vào server, nên restart server thay vì chỉ reload. Reload có thể làm một số plugin hook không đúng thứ tự, khiến placeholder không được đăng ký ổn định. {% endhint %} ## Quick reference Bảng tóm tắt cú pháp để copy nhanh khi cấu hình. ``` %kp_donate_total% %kp_donate_total_today% %kp_donate_total_week% %kp_donate_total_month% %kp_donate_total_year% %kp_donate_server_total% %kp_mocnapserver% %kp_mocnapserver_total% %kp_mocnapserver_progress_1000000% %kp_mocnapserver_percent_1000000% %kp_donate_total_top_player_1% %kp_donate_total_top_amount_1% %kp_donate_total_top_player_1_today% %kp_donate_total_top_amount_1_today% %kp_donate_total_top_player_1_week% %kp_donate_total_top_amount_1_week% %kp_donate_total_top_player_1_month% %kp_donate_total_top_amount_1_month% %kp_donate_total_top_player_1_year% %kp_donate_total_top_amount_1_year% ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://korapay.kingora.net/korapayments-wiki.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.