MTKJPAY/mt-pay

MT Pay - PingPong支付对接

项目简介

本项目实现了PingPong支付平台的内嵌SDK接入，支持收银台模式支付。

功能特性

• ✅ 支付订单创建（checkout接口）
• ✅ MD5/SHA256签名生成和验证
• ✅ 支付回调处理
• ✅ 订单状态查询
• ✅ 收银台页面集成
• ✅ 支付记录管理
• ✅ 预授权支持（AUTH/CAPTURE/VOID）

技术栈

• Spring Boot 4.0.0
• Spring Data JPA
• MySQL
• Lombok
• RestClient

数据库表结构

payment_order（支付订单表）

• 存储支付订单基本信息
• 包含商户订单号、PingPong交易流水号、金额、状态等

payment_record（支付记录表）

• 存储支付操作记录
• 包含回调记录、查询记录等

配置说明

在 application.properties 中配置以下参数：

# PingPong支付配置
pingpong.client-id=your-client-id          # PingPong商户号
pingpong.acc-id=your-acc-id                # PingPong商户店铺编号
pingpong.secret=your-secret-key            # 签名密钥
pingpong.sign-type=MD5                      # 签名类型（MD5或SHA256）
pingpong.gateway=https://sandbox-acquirer-payment.pingpongx.com  # API网关地址
pingpong.mode=sandbox                       # 环境模式（sandbox/test/build）

API接口

1. 创建支付订单

接口地址： POST /api/payment/checkout

请求示例：

{
  "accId": "2018092714313010016291",
  "amount": "20.00",
  "currency": "USD",
  "merchantTransactionId": "MTN193495030728",
  "paymentType": "SALE",
  "shopperResultUrl": "http://your-domain.com/api/callback/result",
  "shopperCancelUrl": "http://your-domain.com/api/callback/result",
  "signType": "MD5",
  "riskInfo": {
    "customer": {
      "firstName": "James",
      "lastName": "LeBron",
      "email": "demo@pingpongx.com",
      "phone": "15988890852",
      "registerTime": "20191101122000",
      "registerIp": "222.126.52.23",
      "orderTime": "20191201122000",
      "orderIp": "222.126.52.23"
    },
    "goods": [{
      "name": "Macaron",
      "description": "Colorful macaron",
      "sku": "20191201331",
      "averageUnitPrice": "20",
      "number": "1",
      "virtualProduct": "N"
    }],
    "shipping": {
      "firstName": "James",
      "lastName": "LeBron",
      "phone": "13588185079",
      "street": "1986 Broad Street",
      "postcode": "35222",
      "city": "Birmingham",
      "state": "Alabama",
      "country": "US"
    },
    "billing": {
      "firstName": "James",
      "lastName": "LeBron",
      "phone": "13588185079",
      "street": "1986 Broad Street",
      "postcode": "35222",
      "city": "Birmingham",
      "state": "Alabama",
      "country": "US"
    }
  },
  "notificationUrl": "http://your-domain.com/api/callback/pingpong"
}

响应示例：

{
  "code": "0000",
  "message": "订单创建成功",
  "data": {
    "merchantTransactionId": "MTN193495030728",
    "token": "vr_YVR8u7rn7C1gG97DOg5W0OxzazxNYIE56ShWjA4lJrY4wchTnb47oNmp-9ubP",
    "paymentUrl": "https://sandbox-pay-checkout.pingpongx.com/index.html?token=...",
    "status": "PENDING"
  }
}

2. 查询订单状态

接口地址： GET /api/payment/order/{merchantTransactionId}

3. 获取收银台页面

接口地址： GET /api/payment/checkout/page?token={token}

4. 支付回调接口

接口地址： POST /api/callback/pingpong

5. 支付结果页面

接口地址： GET /api/callback/result?merchantTransactionId={id}&status={status}

使用流程

1. 创建支付订单

   • 调用 /api/payment/checkout 接口创建订单
   • 获取返回的 token

2. 跳转到收银台

   • 方式1：直接使用返回的 paymentUrl 跳转
   • 方式2：调用 /api/payment/checkout/page?token={token} 获取收银台页面

3. 用户完成支付

   • 用户在收银台页面完成支付
   • 支付完成后跳转到 shopperResultUrl

4. 接收回调通知

   • PingPong会异步调用 notificationUrl 通知支付结果
   • 系统自动更新订单状态

注意事项

1. 订单号唯一性：merchantTransactionId 必须全局唯一，不可重复
2. 金额格式：amount 必须精确到两位小数，如 "20.00"
3. 环境模式：开发测试使用 sandbox，生产环境必须使用 build
4. 签名验证：所有回调都会进行签名验证，确保数据安全
5. 风控信息：riskInfo 中的 shipping、billing、goods 不能为空，影响交易成功率
6. REVIEW状态：如果订单状态为 REVIEW，需要及时进行内部审核

预授权功能

AUTH（预授权）

• 在创建订单时设置 paymentType 为 AUTH

CAPTURE（预授权完成）

• 调用二次交易接口，设置 paymentType 为 CAPTURE
• 需要在预授权成功后的7天内完成

VOID（预授权撤销）

• 调用二次交易接口，设置 paymentType 为 VOID
• 只能全额撤销

开发说明

项目结构

com.mtkj.mtpay/
├── config/          # 配置类
├── controller/       # 控制器
├── dto/             # 数据传输对象
├── entity/          # 实体类
├── exception/       # 异常处理
├── repository/      # 数据访问层
└── service/         # 业务服务层

核心服务

• SignatureService：签名生成和验证服务
• PingPongPayService：PingPong API调用服务
• PaymentOrderService：支付订单业务服务
• CallbackService：回调处理服务

数据库初始化

项目启动后，JPA会自动创建表结构。也可以手动执行SQL：

-- 根据实体类自动生成，或参考实体类定义手动创建

测试

1. 配置沙箱环境参数
2. 调用创建订单接口
3. 使用沙箱测试卡号完成支付测试

许可证

MIT