pingpp-pay
📖 技能介紹
name: pingpp-pay description: 在現有 Java Spring Boot 專案中整合 Ping++ 支付 SDK（pingpp-java）。生成 SDK 配置、Service 層、Webhook 處理器及單元測試，覆蓋付款（Charge）、退款（Refund）、企業付款（Transfer）、批次付款（BatchTransfer）、紅包（RedEnvelope）、訂單（Order）等核心介面。當用戶提到 Ping++、pingpp、PingPlusPlus、聚合支付整合、接入支付 SDK、Charge 建立、Webhooks 驗籤時觸發。
pingpp-pay
在現有 Java Spring Boot 專案中整合 Ping++ 支付 SDK（com.pingxx:pingpp-java）。
- SDK 原始碼：https://github.com/pingplusplus/pingpp-java
- 介面文件：https://www.pingxx.com/api/
- 幫助中心： https://help.pingxx.com/
- SDK 版本：2.5.6，要求 JDK 8+
使用時機
觸發條件：
- 使用者要求在專案中接入/對接/整合 Ping++ 支付
- 使用者提到 "Charge 建立"、"Webhooks 驗籤"、"企業付款 Transfer"、"退款 Refund" 並需要寫程式碼
不觸發條件：
- 使用者只是討論支付業務邏輯而不需要寫程式碼
- 使用者對接其他非 Ping++ 的支付系統
前置條件
執行本 Skill 前，使用者需已獲取：
| 準備項 | 說明 |
|---|---|
| API Key | Dashboard → 【企業面板】 →【開發引數】→ Secret Key（sk_test_ 或 sk_live_） |
| App ID | Dashboard → 應用首頁（app_ 開頭） |
| 商戶私鑰 | 自行生成 RSA 金鑰對，在 Dashboard →【企業面板】 →【開發引數】商戶 RSA 公鑰上傳 |
| Ping++ 公鑰 | Dashboard →【企業面板】 →【開發引數】→ Ping++ 公鑰，用於 Webhooks 驗籤 |
TestKey（sk_test_）不產生真實交易，開發除錯使用。
關鍵規則
- Charge 返回客戶端必須用
charge.toString()— 該方法返回正確的 JSON 字串，不要用其他序列化方式 - 原始 POST Body 用於驗籤 — Webhooks 驗籤必須使用原始 HTTP Body 位元組，不能經過 JSON 解析再序列化
- PingppException 是 checked exception — 所有 SDK 方法呼叫必須用 try-catch 包裹
想要更強大的技能外掛，就來小蔥技能站7w4.net看看吧。
- Webhooks 必須返回 HTTP 200 — 否則 Ping++ 會重試推送，須結合冪等控制
- verifyPublicKey 是 Ping++ 平臺公鑰 — 非商戶自己的公鑰，混用將導致驗籤永遠失敗
- TestKey 只能呼叫測試介面 — 不要用 TestKey 查詢真實交易資料
核心工作流程
第一步：確認對接引數
向用戶確認：
- API Key（Test 還是 Live）
- App ID
- 需要接入的介面（付款 / 退款 / 企業付款 / 紅包 / 訂單 等）
- 是否需要 Webhooks 通知及回撥地址
第二步：分析現有專案
掃描當前工作目錄，瞭解：
- 構建工具（Maven/Gradle）
- 根包路徑
- 現有配置格式（yml/properties）
- 是否已有支付模組
第三步：整合 SDK
按 sdk-setup.md 完成：
- 新增 Maven/Gradle 依賴
- 生成
PingppConfig配置類 - 在
application.yml中新增配置項
第四步：生成整合程式碼
按 code-generation.md 在專案包結構下生成：
ChargeService（必須）RefundService（按需）TransferService（按需）PingppWebhookController（如需 Webhooks）PingppPaymentException
具體 API 方法簽名和渠道引數見 api-reference.md。
第五步：Webhooks 配置
如需非同步通知，按 webhooks.md 生成 Controller，並提示使用者：
- 將回調 URL 配置到 Dashboard →【應用設定】→【Webhooks】
- 確認
pingpp_public_key.pem已放到src/main/resources/
第六步：編譯與測試
硬性要求：為所有接入的介面生成單元測試，查詢類測試（retrieve、list）必須在 TestKey 環境通過。
Step 1: 提示使用者 mvn clean compile / gradle build 驗證編譯
Step 2: 生成單元測試（寫入類測試加 @Disabled 註釋，待使用者填入真實資料啟用）
Step 3: 查詢類測試必須通過 → 驗證 SDK 連通性和簽名正確性
Step 4: 向用戶報告測試結果
技術參考
- SDK 安裝與初始化：sdk-setup.md
- API 方法與渠道引數：api-reference.md
- Webhooks 驗籤與處理：webhooks.md
- 程式碼生成規範與模板：code-generation.md
🤖 AI 評測
這個 Skill 質量中規中矩，文件結構清晰、說明詳細，對常見的支付場景覆蓋較全，程式碼模板直接可用。主要優點是流程完整、規則明確；不足之處是部分文件內容不完整，程式碼示例比較基礎，生產環境使用前需要補充一些額外工作。總體來說可用於快速入門，但要用於生產專案還需要自行完善。
