Ping++ 支付 Java SDK 集成

要解决的问题

在 Java Spring Boot 项目里接入 Ping++ 支付，真正的工作量往往不在「调通一个接口」，而是踩进几个隐蔽的坑：Charge 对象序列化给客户端时格式不对导致前端解析失败；Webhooks 验签时把 body 重新 JSON 序列化了一遍，导致签名永远不匹配；把 PingppException 当成 unchecked exception 漏掉 try-catch，编译直接报错。这些细节散落在 SDK 文档各处，缺少一个统一的落地路径。

这个技能要做的，就是把这些容易出错的点固化成一套可执行的集成流程，针对 com.pingxx:pingpp-java（2.5.6，JDK 8+）生成项目结构内的代码。

它如何工作

• 确认对接参数：先和使用者对齐 API Key（Test 还是 Live）、App ID、需要接入的接口范围（付款、退款、企业付款、红包等），以及是否需要 Webhooks 回调。
• 分析现有项目：扫描工作目录，识别构建工具是 Maven 还是 Gradle、根包路径、配置文件格式，以及是否已有支付模块。
• 集成 SDK：按 sdk-setup.md 添加依赖、生成 PingppConfig 配置类、写入 application.yml 配置项。
• 生成业务代码：按 code-generation.md 产出 ChargeService（必需）、RefundService 与 TransferService（按需）、PingppWebhookController（如需异步通知），以及统一的 PingppPaymentException。渠道参数和 API 签名参考 api-reference.md。
• Webhooks 配置：生成回调 Controller，并提示使用者把回调地址配到 Dashboard，确认 pingpp_public_key.pem 已放进 src/main/resources/。
• 编译与测试：为所有接入的接口生成单元测试，查询类（retrieve、list）必须在 TestKey 环境下通过。

关键注意点

集成前需要先备好四项参数：API Key（sk_test_ 或 sk_live_）、App ID、商户 RSA 私钥，以及 Dashboard 上提供的 Ping++ 平台公钥。几条硬规则值得特别留意：

• 返回给客户端的 Charge 必须使用 charge.toString()，不要用其他序列化方式，否则 JSON 结构会偏离预期。
• Webhooks 验签必须基于原始 HTTP Body 字节，经过 JSON 解析再序列化会破坏签名。
• verifyPublicKey 校验的是 Ping++ 平台公钥，不是商户自己的公钥，混用会导致验签一直失败。
• PingppException 是 checked exception，所有 SDK 调用都要包在 try-catch 里。
• Webhooks 接口必须返回 HTTP 200，否则平台会持续重试，需要配合幂等控制。
• TestKey 只能走测试接口，不能用来查询真实交易数据。

如果只是想讨论支付业务逻辑而不写代码，或对接的是 Ping++ 以外的支付系统，这个技能不会触发。