# jlpay-sdk-php

**Repository Path**: jlpaydemo/jlpay-sdk-php

## Basic Information

- **Project Name**: jlpay-sdk-php
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-20
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 嘉联支付开放平台 PHP SDK

这是嘉联支付开放平台的PHP SDK，为第三方应用提供与嘉联支付系统集成的接口能力。SDK封装了HTTP请求、签名验证、数据加解密等底层功能，简化开发者的接入流程。

## 1. 项目安装说明

### 环境要求

- PHP >= 7.4
- 以下PHP扩展：
  - ext-json
  - ext-openssl
  - ext-curl
- 以下依赖包：
  - lpilp/guomi ^1.0（国密算法库）

### 安装方法


#### 方法一：从源码安装

```bash
git clone https://gitee.com/jlpay/jlpay-sdk-php.git
cd jlpay-sdk-php
composer install
```

## 2. 功能特性

### 🔐 国密算法支持
- ✅ **SM2椭圆曲线加密算法**（数字签名、签名验证、公钥加密、私钥解密）
- ✅ **SM4对称加密算法**（ECB模式加解密）
- ✅ **SM3哈希算法**（消息摘要计算）
- ✅ **PEM格式密钥解析**

### 📡 HTTP请求处理
- ✅ **自动签名验签**（SM2数字签名）
- ✅ **HTTP请求封装**（支持GET/POST）
- ✅ **异常处理机制**
- ✅ **请求日志记录**

### 💼 业务功能
- ✅ **商户服务**（商户进件新增/修改、申请单查询/作废、实名认证查询；商户进件支持 5 种场景：企业+对公/法人/授权对私/授权对公、小微+电子签约）
- ✅ **接口分账**（入账方注册支持出账方商户号 `ledger_mch_id`；入账方查询/开通响应支持 `mch_id`、电子协议链接 `sign_link`；入账方签约信息修改-获取新签约链接）
- ✅ **交易**（银联行业码支付-获取 user_id；异步退款申请支持 `notify_url`）
- ✅ **文件上传功能**（图片、视频、PDF上传）
- ✅ **敏感数据自动加密**

### 🛠️ 开发工具
- ✅ **完整的示例代码**
- ✅ **单元测试支持**
- ✅ **代码格式化工具**
- ✅ **详细的错误日志**

## 3. 示例使用说明

SDK提供了丰富的示例代码，位于`examples`目录下：

### 基础配置示例

```php
<?php
use JLPay\Core\Config;

// 创建配置对象
$config = new Config([
    'app_id' => 'YOUR_APP_ID',
    'base_url' => 'https://api.jlpay.com',
    'org_private_key' => '-----BEGIN EC PRIVATE KEY-----
YOUR_PRIVATE_KEY_CONTENT
-----END EC PRIVATE KEY-----',
    'org_public_key' => '-----BEGIN PUBLIC KEY-----
YOUR_PUBLIC_KEY_CONTENT
-----END PUBLIC KEY-----',
    'jlpay_public_key' => '-----BEGIN PUBLIC KEY-----
JLPAY_PUBLIC_KEY_CONTENT
-----END PUBLIC KEY-----'
]);
```

### 商户进件示例

查看 `examples/merchant_incoming_demo.php` 了解如何使用SDK进行商户进件操作。

```php
<?php
use JLPay\Services\MerchantService;
use JLPay\Models\Merchant\MerchantIncomingAddRequest;

// 创建商户服务
$merchantService = new MerchantService($config);

// 创建商户进件请求
$request = new MerchantIncomingAddRequest();
$request->setMerchantName('测试商户');
$request->setBusinessLicense('123456789');
// ... 设置其他必要参数

// 发送请求
$response = $merchantService->merchantIncomingAdd($request);

if ($response->isSuccess()) {
    echo "商户进件成功，订单号：" . $response->getOrderNo();
} else {
    echo "商户进件失败：" . $response->getRetMsg();
}
```

### 文件上传示例

查看 `examples/merchant_file_upload_demo.php` 了解如何使用SDK进行文件上传操作。

```php
<?php
use JLPay\Services\FileService;
use JLPay\Models\Upload\ImageUploadRequest;

// 创建文件服务
$fileService = new FileService($config);

// 创建图片上传请求
$request = new ImageUploadRequest();
$request->setFileFromPath('/path/to/image.jpg');
$request->setMetaWithDigest('image.jpg'); // 自动计算SM3摘要

// 上传文件
$response = $fileService->uploadImage($request);

if ($response->isSuccess()) {
    echo "文件上传成功，媒体ID：" . $response->getMediaId();
} else {
    echo "文件上传失败：" . $response->getRetMsg();
}
```

### 国密算法使用示例

```php
<?php
use JLPay\Utils\SmUtils;

// SM2数字签名
$message = "待签名的数据";
$signature = SmUtils::sm2Sign($message, $privateKeyHex, $publicKeyHex);

// SM2签名验证
$isValid = SmUtils::sm2Verify($message, $signature, $publicKeyHex);

// SM4加解密
$sm4Key = SmUtils::generateSm4Key();
$encrypted = SmUtils::sm4EcbEncrypt("敏感数据", $sm4Key);
$decrypted = SmUtils::sm4EcbDecrypt($encrypted, $sm4Key);

// SM3摘要计算
$digest = SmUtils::getDigestByType('SM3', "测试数据");
```

### 版本信息使用示例

查看 `examples/version_demo.php` 了解如何获取SDK版本信息。

```php
<?php
use JLPay\Core\Version;

// 获取版本号
$version = Version::getVersion(); // "1.0.2"

// 获取完整版本信息
$fullVersion = Version::getFullVersion(); // "JLPay PHP SDK v1.0.2 (2025-08-04)"

// 获取用户代理字符串（用于HTTP请求）
$userAgent = Version::getUserAgent(); // "JLPay PHP SDK/1.0.2 (PHP/8.2.28)"

// 获取详细版本信息数组
$versionInfo = Version::getVersionInfo();
```

## 4. 测试说明

SDK提供了完整的单元测试用例，位于`tests`目录下。

### 运行所有测试

```bash
composer test
```

### 运行单个测试文件

```bash
./vendor/bin/phpunit tests/Utils/SmUtilsTest.php
```

### V1.0.3 单测（不依赖 PHPUnit）

需求相关模型与服务可在不安装 PHPUnit 的情况下快速自测：

```bash
php tests/run_requirements_modified.php
```

通过则输出 `All checks passed.`；也可使用 PHPUnit 运行 `tests/RequirementsModifiedTest.php`。

### 测试覆盖率

生成测试覆盖率报告：

```bash
composer test-coverage
```

报告将生成在`coverage`目录中，您可以打开`coverage/index.html`查看详细报告。

### 代码格式化

```bash
# 检查代码格式
composer cs-check

# 自动修复代码格式
composer cs-fix
```

## 5. 项目结构

```
jlpay-sdk-php/
├── src/
│   ├── Core/                    # 核心功能
│   │   ├── OrgConfig.php       # 机构配置类
│   │   ├── DemoConfig.php      # 示例配置
│   │   ├── SignVerifier.php    # 签名验证器
│   │   ├── Version.php         # 版本信息
│   │   └── Http/               # HTTP相关
│   │       ├── HttpClient.php          # HTTP客户端
│   │       ├── HttpClientWrapper.php   # HTTP客户端包装器
│   │       ├── HttpRequest.php         # HTTP请求类
│   │       ├── HttpResponse.php        # HTTP响应类
│   │       ├── HttpExceptions.php      # HTTP异常类
│   │       └── DefaultHttpClientBuilder.php # 默认HTTP客户端构建器
│   ├── Services/               # 业务服务
│   │   ├── BaseService.php     # 基础服务类
│   │   ├── MerchantService.php # 商户服务
│   │   ├── FileService.php     # 文件服务
│   │   ├── Ledger/             # 分账相关
│   │   │   ├── Merchconf/MerchconfService.php   # 商户配置（入账方注册/查询/签约信息修改等）
│   │   │   ├── BalanceSplit/  # 分账
│   │   │   └── Bill/          # 账单
│   │   ├── Trans/              # 交易相关
│   │   │   ├── Common/GetOpenidService.php     # 获取OpenID/银联user_id
│   │   │   ├── Refunds/        # 异步退款
│   │   │   ├── B2c/、C2b/、Mini/、Union/
│   │   │   └── ...
│   │   └── Openmerch/          # 开放商户（进件、变更、设备、查询等）
│   ├── Models/                 # 数据模型
│   │   ├── BaseRequest.php     # 基础请求类
│   │   ├── BaseResponse.php    # 基础响应类
│   │   ├── Merchant/          # 商户进件等
│   │   │   ├── MerchantIncomingAddRequest.php
│   │   │   ├── MerchantIncomingAddResponse.php
│   │   │   ├── MerchantIncomingModifyRequest.php
│   │   │   ├── MerchantIncomingModifyResponse.php
│   │   │   ├── RealnameQueryRequest.php / RealnameQueryResponse.php
│   │   │   ├── MerchantOrderQueryRequest.php / MerchantOrderQueryResponse.php
│   │   │   └── MerchantOrderCancelRequest.php / MerchantOrderCancelResponse.php
│   │   ├── Ledger/Merchconf/   # 分账-商户配置（V1.0.3）
│   │   │   ├── MerchRevOpenRequest.php / MerchRevOpenResponse.php   # 入账方注册
│   │   │   ├── MerchRevQueryRequest.php / MerchRevQueryResponse.php # 入账方查询
│   │   │   ├── MerchRevModifySignUrlRequest.php / MerchRevModifySignUrlResponse.php # 签约信息修改
│   │   │   └── ...
│   │   ├── Trans/              # 交易模型
│   │   │   ├── Common/GetOpenidRequest.php / GetOpenidResponse.php
│   │   │   ├── Common/GetUnionPayUserIdRequest.php / GetUnionPayUserIdResponse.php  # V1.0.3 银联user_id
│   │   │   ├── Refunds/RefundsRequest.php / RefundsResponse.php    # 异步退款（含notify_url）
│   │   │   └── ...
│   │   ├── Openmerch/          # 开放商户模型
│   │   ├── BaseData/           # 基础数据（银行列表、MCC等）
│   │   └── Upload/             # 文件上传
│   │       ├── FileUploadRequest.php / FileUploadResponse.php
│   │       ├── ImageUploadRequest.php、VideoUploadRequest.php、PdfUploadRequest.php
│   │       └── ...
│   ├── Utils/                  # 工具类
│   │   ├── SmUtils.php         # 国密工具类
│   │   ├── Logger.php          # 日志工具
│   │   └── DemoRequestHandler.php
│   └── Exceptions/             # 异常类
│       ├── ConfigException.php、CryptoException.php
│       ├── HttpExecutionException.php、SignVerifyException.php
│       └── ...
├── examples/                   # 示例代码
│   ├── base/                   # 基础数据示例
│   ├── ledger/merchconf/       # 分账-商户配置（入账方注册/查询/签约信息修改等）
│   ├── trans/common/           # 交易-获取OpenID、银联user_id等
│   ├── trans/refunds/          # 异步退款
│   ├── openmerch/register/     # 商户进件、进件5场景示例
│   ├── merchant_file_upload_demo.php
│   ├── version_demo.php
│   └── sample_files/
├── tests/                      # 单元测试
│   ├── RequirementsModifiedTest.php    # V1.0.3 需求明细 PHPUnit 用例
│   ├── run_requirements_modified.php  # V1.0.3 需求明细自测脚本（不依赖 PHPUnit）
│   ├── Utils/SmUtilsTest.php   # 国密工具测试
│   └── logs/
├── composer.json
├── phpunit.xml
├── .php-cs-fixer.php
└── README.md


## 6. API接口说明

### 商户相关接口

- **商户进件新增**：`/open/merch/access/incoming/add`
- **商户进件修改**：`/open/merch/access/incoming/modify`
- **微信支付宝认证查询**：`/open/merch/access/realname/query`
- **商户申请单查询**：`/open/merch/access/incoming/query`
- **商户申请单作废**：`/open/merch/access/incoming/cancel`

### 文件上传接口

- **图片上传**：`/base/file/upload/image`
- **视频上传**：`/base/file/upload/video`
- **PDF上传**：`/base/file/upload/pdf`

## 7. 常见问题

### 密钥格式问题

SDK使用PEM格式的密钥，如果您的密钥不是PEM格式，需要先进行转换：

```php
// 确保密钥包含正确的头部和尾部标识
$privateKeyPem = "-----BEGIN EC PRIVATE KEY-----\n" . 
                 chunk_split($privateKeyBase64, 64, "\n") . 
                 "-----END EC PRIVATE KEY-----";
```

### 签名验证失败

- 请检查密钥是否正确
- 请检查请求参数是否正确
- 请检查服务器时间是否同步
- 确保字符编码为UTF-8

### 文件上传失败

- 检查文件大小是否超过限制（图片5MB，视频10MB，PDF5MB）
- 确保文件格式正确
- 检查meta信息是否包含必需的filename、alg、abstract字段

### 国密算法相关

- 确保已正确安装lpilp/guomi依赖包
- 检查PHP版本是否满足要求（>= 7.4）
- 确保OpenSSL扩展已启用

## 8. 版本说明

| 版本 | 日期        | 版本说明 |
|------|-----------|----------|
| v1.0.3 | 2026/2/3  | V1.0.3 需求明细：接口分账（入账方注册 ledger_mch_id/mch_id/sign_link、入账方查询 sign_link、入账方签约信息修改）；交易（银联行业码获取 user_id、异步退款 notify_url）；商户进件 5 种场景示例；自测脚本 |
| v1.0.2 | 2025/8/4  | 补充收银台(收银托管预下单、订单状态查询、撤单、退款)、清结算、资金管控、分账、 商户管理、交易模块demo                                                                                  |
| v1.0.1 | 2025/6/10 | 新增文件上传功能，支持图片、视频、PDF上传；完善商户进件功能；优化错误处理和日志记录 |
| v1.0.0 | 2025/5/20 | 初始版本，包含SM2/SM3/SM4国密算法支持、HTTP请求封装、自动签名验签、商户基础服务 |

## 9. 注意事项

1. **字符编码**: 所有字符串使用UTF-8编码
2. **密钥安全**: 生产环境中请妥善保管私钥，避免泄露
3. **网络安全**: 建议在生产环境中使用HTTPS协议
4. **错误处理**: 请根据返回的错误码进行相应的错误处理
5. **日志记录**: 建议在生产环境中适当调整日志级别

## 10. 联系方式

如果您有任何问题或建议，请通过以下方式与我们联系：

- 邮箱：support@jlpay.com
- 技术支持：sdk@jlpay.com
- GitHub Issues：https://github.com/jlpay/jlpay-sdk-php/issues

## 11. 许可证

本项目基于 MIT 许可证开源，详情请参阅 [LICENSE](LICENSE) 文件。