shield_lock
JinDaGe
← Back to skills
extension
Category: OtherAPI key required

pingpp-pay

在现有 Java Spring Boot 项目中集成 Ping++ 支付 SDK（pingpp-java）。生成 SDK 配置、Service 层、Webhook 处理器及单元测试，覆盖付款（Charge）、退款（Refund）、企业付款（Transfer）、批量付款（BatchTransfer）、红包（RedEnvelope）、订单（Order）等核心接口。当用户提到 Ping++、pingpp、PingPlusPlus、聚合支付集成、接入支付 SDK、Charge 创建、Webhooks 验签时触发。

personAuthor: u_84b1e9fehubenterprise
downloadDownload package

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: 向用户报告测试结果

技术参考