商户接入文档

一、概述

本文档说明如何接入MK聚合支付系统API，使用RSA2签名进行接口调用。

1.1 签名方式

• 签名算法: RSA2 (SHA256WithRSA)
• 密钥长度: 2048位或4096位
• 签名方式: 商户私钥签名，平台公钥验签（非对称加密）

1.2 接口地址

• 生产环境: https://api.mkpay.com
• 测试环境: https://api-test.mkpay.com

二、密钥管理

2.1 密钥生成

商户需要生成RSA密钥对：

方式1: 使用OpenSSL生成

# 生成2048位私钥
openssl genrsa -out private_key.pem 2048

# 导出公钥（X509格式）
openssl rsa -in private_key.pem -pubout -out public_key.pem

# 转换为Base64格式（PKCS8私钥）
openssl pkcs8 -topk8 -inform PEM -in private_key.pem -outform PEM -nocrypt | base64

# 转换为Base64格式（X509公钥）
cat public_key.pem | base64

方式2: 使用Java生成

KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("RSA");
keyPairGen.initialize(2048);
KeyPair keyPair = keyPairGen.generateKeyPair();
RSAPublicKey publicKey = (RSAPublicKey) keyPair.getPublic();
RSAPrivateKey privateKey = (RSAPrivateKey) keyPair.getPrivate();

// Base64编码
String publicKeyBase64 = Base64.getEncoder().encodeToString(publicKey.getEncoded());
String privateKeyBase64 = Base64.getEncoder().encodeToString(privateKey.getEncoded());

2.2 公钥上传

商户需要将公钥上传到平台：

1. 登录管理后台
2. 进入"密钥管理"页面
3. 上传公钥（Base64编码的X509格式）
4. 平台验证后激活密钥

三、接口调用

3.1 请求参数

所有API接口必须包含以下公共参数：

3.2 签名生成步骤

1. 参数排序: 除sign外所有参数按字母顺序排序
2. 参数拼接: 格式为 key1=value1&key2=value2&...
3. RSA2签名: 使用商户私钥对拼接后的字符串进行SHA256WithRSA签名
4. Base64编码: 将签名结果进行Base64编码

3.3 示例代码

Java示例:

import org.jeecg.pay.sdk.PayClient;
import java.util.HashMap;
import java.util.Map;

// 初始化客户端
PayClient client = new PayClient(
    "https://api.mkpay.com",
    "PLATFORM001",
    "MCH001",
    "YOUR_PRIVATE_KEY_BASE64"
);

// 构建请求参数
Map<String, String> params = new HashMap<>();
params.put("orderNo", "ORDER123456");
params.put("amount", "10000");
params.put("callbackUrl", "https://merchant.com/callback");

// 调用支付接口
String response = client.callApi("/api/pay", params);

3.4 时间戳和Nonce

• timestamp: 当前Unix时间戳（秒），有效期5分钟
• nonce: 32位随机字符串，确保请求唯一性

四、响应处理

4.1 响应格式

{
    "code": 200,
    "message": "success",
    "data": {
        "orderNo": "ORDER123456",
        "status": "SUCCESS"
    }
}

4.2 错误码

五、SDK使用

5.1 Java SDK

Maven依赖:

<dependency>
    <groupId>org.jeecg</groupId>
    <artifactId>pay-sdk-java</artifactId>
    <version>1.0.0</version>
</dependency>

使用示例:

PayClient client = new PayClient(baseUrl, platformCode, mchCode, privateKey);
String response = client.callApi("/api/pay", params);

六、注意事项

1. 私钥安全: 私钥必须妥善保管，不得泄露
2. 时间同步: 确保服务器时间准确，避免时间戳验证失败
3. Nonce唯一性: 每次请求必须使用不同的nonce
4. 重试机制: 建议实现自动重试机制（最多3次）
5. 幂等性: 支付接口支持幂等性，重复请求不会重复处理

七、测试环境

测试环境提供沙箱功能，可以模拟各种场景：

• 正常支付流程
• 签名验证失败
• 重放攻击检测
• 限流测试

测试环境密钥可通过管理后台申请。