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_）不产生真实交易，开发调试使用。

关键规则

1. Charge 返回客户端必须用 charge.toString() — 该方法返回正确的 JSON 字符串，不要用其他序列化方式
2. 原始 POST Body 用于验签 — Webhooks 验签必须使用原始 HTTP Body 字节，不能经过 JSON 解析再序列化
3. PingppException 是 checked exception — 所有 SDK 方法调用必须用 try-catch 包裹
4. Webhooks 必须返回 HTTP 200 — 否则 Ping++ 会重试推送，须结合幂等控制
5. verifyPublicKey 是 Ping++ 平台公钥 — 非商户自己的公钥，混用将导致验签永远失败
6. TestKey 只能调用测试接口 — 不要用 TestKey 查询真实交易数据

核心工作流程

第一步：确认对接参数

向用户确认：

• API Key（Test 还是 Live）
• App ID
• 需要接入的接口（付款 / 退款 / 企业付款 / 红包 / 订单 等）
• 是否需要 Webhooks 通知及回调地址

第二步：分析现有项目

扫描当前工作目录，了解：

• 构建工具（Maven/Gradle）
• 根包路径
• 现有配置格式（yml/properties）
• 是否已有支付模块

第三步：集成 SDK

按 sdk-setup.md 完成：

1. 添加 Maven/Gradle 依赖
2. 生成 PingppConfig 配置类
3. 在 application.yml 中添加配置项

第四步：生成集成代码

按 code-generation.md 在项目包结构下生成：

• ChargeService（必须）
• RefundService（按需）
• TransferService（按需）
• PingppWebhookController（如需 Webhooks）
• PingppPaymentException

具体 API 方法签名和渠道参数见 api-reference.md。

第五步：Webhooks 配置

如需异步通知，按 webhooks.md 生成 Controller，并提示用户：

1. 将回调 URL 配置到 Dashboard →【应用设置】→【Webhooks】
2. 确认 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