# threeypay-sdk

**Repository Path**: yangzai2018/threeypay-sdk

## Basic Information

- **Project Name**: threeypay-sdk
- **Description**: 3YPay (汇联支付) PHP SDK
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-25
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3ypay SDK

[![PHP Version](https://img.shields.io/packagist/php-v/threeypay/sdk)](https://packagist.org/packages/threeypay/sdk)
[![License](https://img.shields.io/packagist/l/threeypay/sdk)](https://packagist.org/packages/threeypay/sdk)

### V1.0.0 内部测试版本，仅供参考使用。请务必参照对接文档进行对接
1. 3ypay (汇联支付) PHP SDK，支持统一支付、交易查询、退款、转账、分账等功能。
2. 具体参数说明，请查看 [API 文档](https://doc.3ypay.com/)。
3. 请务必对照文档进行配置，并确保代码正确运行。




## 安装

### 方式一：使用 Composer 安装（推荐）

```bash
composer require 3ypay/sdk
```

### 方式二：手动安装

1. 克隆或下载 SDK 到项目目录
2. 在项目根目录执行：

```bash
composer install
```

### 环境要求

- **PHP 版本**: >= 7.4 或 >= 8.0
- **必需扩展**:
  - `openssl` (用于签名和验签)
  - `json` (用于数据处理)
  - `curl` (用于 HTTP 请求)
- **依赖库**: GuzzleHttp >= 7.0


## 快速开始

### 1. 初始化 SDK

```php
<?php

require_once __DIR__ . '/vendor/autoload.php';

use ThreeYPay\ThreeYPay;

// 配置参数
$appId = 'YOUR_APP_ID';                    // 应用 APPID，如 APP_00137105505
$privateKey = 'YOUR_PRIVATE_KEY';          // 商户私钥 (RSA2)
$platformPublicKey = 'YOUR_PLATFORM_PUBLIC_KEY'; // 平台公钥
$isSandbox = true;                         // 是否使用测试环境（true:沙箱 false:正式）

// 初始化 SDK
$pay = new ThreeYPay($appId, $privateKey, $platformPublicKey, $isSandbox);
```

### 2. 获取配置参数

- **appId**: 在 [3YPay 开放平台](https://open.3ypay.com/) 申请
- **privateKey**: RSA2 私钥，用于请求签名
- **platformPublicKey**: 平台 RSA2 公钥，用于响应验签
- **sandbox**: 测试环境设为 `true`，生产环境设为 `false`

### 3. 订单号规范

**重要提示**: 商户订单号必须在 18-64 个字符之间，建议使用以下格式：

```php
// 推荐格式：前缀 + 日期时间 + 随机数
$mchOrderNo = 'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999);
// 示例：ORDER_20260306203431_9516
```

## 功能模块

### 1. 统一下单/支付 (Payment)

#### 支付宝扫码支付

```php
$result = $pay->payment()->alipay(
    'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999), // 商户订单号（18-64 位）
    '0.01',              // 订单金额（单位：元）
    '测试商品',           // 订单标题
    '商品描述',           // 订单描述
    'https://yourdomain.com/notify.php', // 异步通知地址
    '127.0.0.1',         // 客户端IP
    time() * 1000 + 30*60*1000 // 过期时间 (毫秒)
);

// 解析结果
if ($result['code'] == 200) {
    echo '支付订单号：' . $result['data']['payOrderNo'];
    echo '支付二维码：' . $result['data']['payData'];
}
```

#### 微信扫码支付

```php
$result = $pay->payment()->wechatNative(
    'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999),
    '0.01',
    '测试商品',
    '商品描述',
    'https://yourdomain.com/notify.php',
    '127.0.0.1',
    time() * 1000 + 30*60*1000
);
```

#### 微信 JSAPI 支付（小程序/公众号）

```php
$result = $pay->payment()->wechatJsapi(
    'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999),
    '0.01',
    '测试商品',
    '商品描述',
    'https://yourdomain.com/notify.php',
    '127.0.0.1',
    time() * 1000 + 30*60*1000,
    'user_openid_here'  // 用户 openid（必填）
);
```

#### 支付宝 JS 支付（小程序）

```php
$result = $pay->payment()->alipayJs(
    'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999),
    '0.01',
    '测试商品',
    '商品描述',
    'https://yourdomain.com/notify.php',
    '127.0.0.1',
    time() * 1000 + 30*60*1000,
    'zhangsan@alipay.com'  // 买家支付宝账号（必填）
);
```

#### 微信 APP 支付

```php
$result = $pay->payment()->wechatApp(
    'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999),
    '0.01',
    '测试商品',
    '商品描述',
    'https://yourdomain.com/notify.php',
    '127.0.0.1',
    time() * 1000 + 30*60*1000
);
```

#### 银联支付

```php
$result = $pay->payment()->unionpay(
    'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999),
    '0.01',
    '测试商品',
    '商品描述',
    'https://yourdomain.com/notify.php',
    '127.0.0.1',
    time() * 1000 + 30*60*1000
);
```

#### 统一下单（自定义参数）

```php
$result = $pay->payment()->pay([
    'mchOrderNo' => 'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999),
    'productCode' => 'Ali-PAY',       // 产品码
    'paySubType' => 'NATIVE',         // 支付子类型
    'subject' => '测试商品',
    'description' => '商品描述',
    'orderAmount' => '0.01',
    'clientIp' => '127.0.0.1',
    'notifyUrl' => 'https://yourdomain.com/notify.php',
    'redirectUrl' => 'https://yourdomain.com/return.php',   // 跳转地址
    'cancelUrl' => 'https://yourdomain.com/cancel.php',     // 取消地址
    'expiredTime' => time() * 1000 + 30*60*1000,
    'attach' => '附加数据',
]);
```

#### 交易查询

**根据支付订单号查询：**

```php
$result = $pay->payment()->queryByPayOrderNo('P202603062034302534880');

if ($result['code'] == 200) {
    $data = $result['data'];
    echo '订单状态：' . $data['state'];  // 0-待支付，1-支付中，2-支付成功，3-支付失败，4-已取消，7-失败
    echo '订单金额：' . $data['orderAmount'];
}
```

**根据商户订单号查询：**

```php
$result = $pay->payment()->queryByMchOrderNo('ORDER_20260306203431_9516');
```

#### 退款

```php
$result = $pay->payment()->refund([
    'payOrderNo' => 'P202603062034302534880', // 支付订单号（必填）
    'amount' => '0.01',                        // 退款金额（必填）
    'mchRefundOrderNo' => 'REFUND_' . date('YmdHis'), // 商户退款订单号（必填）
    'notifyUrl' => 'https://yourdomain.com/refund_notify.php', // 退款通知地址（必填）
    'reason' => '用户申请退款',                 // 退款原因（可选）
]);
```

#### 退款查询

```php
$result = $pay->payment()->queryRefund([
    'mchRefundOrderNo' => 'REFUND_20260306203431', // 商户退款订单号（必填）
]);
```

### 2. 转账 (Transfer)

```php
// 转账到银行卡
$result = $pay->transfer()->transferToBankCard(
    '2088970907720362',                    // 账本ID
    'TRANS_' . time(),                     // 商户订单号
    '0.10',                                // 转账金额
    '测试转账',                             // 订单标题
    'https://yourdomain.com/transfer_notify.php', // 通知地址
    '6222021234567890',                    // 银行卡号
    '张三',                                 // 姓名
    '招商银行',                             // 银行名称
    '1'                                    // 账户类型 (1:对私, 2:对公)
);

// 转账到支付宝
$result = $pay->transfer()->transferToAlipay(
    '2088970907720362',
    'TRANS_' . time(),
    '0.10',
    '测试转账',
    'https://yourdomain.com/transfer_notify.php',
    'zhangsan@alipay.com',
    '张三'
);

// 转账查询
$result = $pay->transfer()->transferQuery([
    'mch_order_no' => 'TRANS_123456789',
]);

// 转账回单申请
$result = $pay->transfer()->receiptApply([
    'mch_order_no' => 'TRANS_123456789',
    'out_biz_no' => 'RECEIPT_' . time(),
]);

// 转账回单下载
$result = $pay->transfer()->receiptDownload([
    'mch_order_no' => 'TRANS_123456789',
]);

// 直付通支付
$result = $pay->transfer()->directPay([
    'mchOrderNo' => 'ORDER_' . time(),
    'productCode' => 'Ali-PAY',
    'paySubType' => 'NATIVE',
    'subject' => '测试商品',
    'description' => '商品描述',
    'orderAmount' => '0.01',
    'notifyUrl' => 'https://yourdomain.com/notify.php',
    'clientIp' => '127.0.0.1',
    'expiredTime' => time() * 1000 + 30*60*1000,
]);

// 直付通退款
$result = $pay->transfer()->directRefund([
    'mchOrderNo' => 'ORDER_123456789',
    'mchRefundOrderNo' => 'REFUND_' . time(),
    'refundAmount' => '0.01',
    'reason' => '用户申请退款',
    'notifyUrl' => 'https://yourdomain.com/refund_notify.php',
]);

// 直付通退款查询
$result = $pay->transfer()->directRefundQuery([
    'refundOrderNo' => 'R202601071444420295',
]);
```

### 3. 分账 (ProfitSharing)

```php
// 请求分账
$receivers = [
    [
        'accountNo' => '2088xxxxxx',
        'amount' => 1,              // 分账金额(单位:分)
        'description' => '分账给商户A',
        'feeRate' => 0,             // 手续费承担比例(0-1之间的小数)
        'isRtc' => 0,               // 是否实时到账(0:否, 1:是)
    ],
];

$result = $pay->profitSharing()->applySimple(
    'ORDER_123456789',                         // 商户订单号
    'P202601121928452056309',                 // 支付订单号
    'BATCH_' . time(),                         // 商户批次号
    $receivers,                                // 分账接收方列表
    'https://yourdomain.com/profit_sharing_notify.php' // 通知地址
);

// 分账查询
$result = $pay->profitSharing()->query([
    'mchBatchNo' => 'BATCH_123456789', // 商户批次号
]);

// 分账完结
$result = $pay->profitSharing()->finish([
    'mchBatchNo' => 'BATCH_123456789',
]);

// 分账退款
$result = $pay->profitSharing()->refund([
    'batchNo' => 'BATCH_123456789',
    'mchBatchNo' => 'BATCH_123456789',
    'mchRefundOrderNo' => 'PS_REFUND_' . time(),
    'notifyUrl' => 'https://yourdomain.com/profit_sharing_refund_notify.php',
    'acctInfos' => [
        [
            'accOrderNo' => 'ACC_123456789',
            'amount' => 1,
            'description' => '分账退款',
        ],
    ],
]);

// 分账退款查询
$result = $pay->profitSharing()->refundQuery([
    'batchNo' => 'BATCH_123456789',
    'mchBatchNo' => 'BATCH_123456789',
    'mchRefundOrderNo' => 'PS_REFUND_xxx',
]);
```

### 4. 账户管理 (Account)

```php
// 账户余额查询
$result = $pay->account()->query();

// 账户余额提现
$result = $pay->account()->withdraw([
    'amount' => '100.00',
    'notifyUrl' => 'https://yourdomain.com/withdraw_notify.php',
]);

// 账户余额转账
$result = $pay->account()->transfer([
    'targetAccountNo' => '2088xxxxxx',
    'amount' => '100.00',
    'notifyUrl' => 'https://yourdomain.com/transfer_notify.php',
]);

// 账户结算记录查询
$result = $pay->account()->querySettleRecords([
    'startTime' => time() * 1000 - 7*24*60*60*1000,
    'endTime' => time() * 1000,
]);
```

### 5. 商户管理 (Merchant)

```php
// 商户进件
$result = $pay->merchant()->entry([
    'merchantName' => '测试商户',
    'merchantType' => 1,
    // ... 其他参数
]);

// 申请单状态查询
$result = $pay->merchant()->queryStatus([
    'applyNo' => 'APPLY_123456789',
]);

// 商户信息变更
$result = $pay->merchant()->update([
    'merchantNo' => 'M202601121928452056309',
    'merchantName' => '新商户名称',
]);

// 信息变更状态查询
$result = $pay->merchant()->queryUpdateStatus([
    'applyNo' => 'UPDATE_123456789',
]);
```

## 回调通知验证

```php
// 接收回调
$rawData = file_get_contents('php://input');
$data = json_decode($rawData, true);

// 验证签名
$pay = new ThreeYPay($appId, $privateKey, $platformPublicKey, $isSandbox);
if ($pay->verifyNotify($data)) {
    // 验证成功，处理业务逻辑
    $bizData = json_decode($data['data'], true);
    
    // 根据通知类型处理
    switch ($data['notifyType']) {
        case 'PAY':
            // 支付通知
            break;
        case 'REFUND':
            // 退款通知
            break;
        case 'TRANSFER':
            // 转账通知
            break;
        case 'PROFIT_SHARING':
            // 分账通知
            break;
    }
    
    echo 'success';
} else {
    // 验证失败
    http_response_code(400);
    echo 'fail';
}
```

## 配置说明

| 参数 | 说明 | 示例 |
|------|------|------|
| appId | 应用 ID，在 3YPay 开放平台申请 | `APP_00137105505` |
| privateKey | 商户 RSA2 私钥，用于请求签名 | `MIIEvQIBADANBgkq...` |
| platformPublicKey | 平台 RSA2 公钥，用于响应验签 | `MIIBIjANBgkq...` |
| sandbox | 是否使用测试环境 (沙箱) | `true`: 沙箱<br>`false`: 正式环境 |

## 环境要求

- **PHP 版本**: >= 7.4 或 >= 8.0
- **必需 PHP 扩展**:
  - `openssl` - 用于 RSA2 签名和验签
  - `json` - 用于 JSON 数据处理
  - `curl` - 用于 HTTP 请求
- **依赖库**: GuzzleHttp >= 7.0

## 常见问题

### 1. SSL 证书问题

如果遇到 `cURL error 60: SSL certificate problem` 错误：

**解决方案 A（推荐）**: 在 php.ini 中配置 CA 证书
```ini
curl.cainfo = "D:\phpstudy_pro\Extensions\cacert.pem"
```

**解决方案 B（仅开发环境）**: 临时禁用 SSL 验证
修改 `src/Client.php` 第 44 行：
```php
'verify' => false,
```

### 2. 订单号长度不合法

错误信息：`商户订单号长度必须在 18 到 64 个字符之间`

**解决方案**: 使用推荐的订单号格式
```php
$mchOrderNo = 'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999);
// 示例：ORDER_20260306203431_9516 (共 24 位)
```

### 3. 商户未认证

错误信息：`当前商户未认证，请通知商户在支付宝搜索“支付宝商家认证助手”小程序`

**解决方案**:
1. 打开支付宝 APP
2. 搜索“支付宝商家认证助手”小程序
3. 完成商户认证流程

## 测试说明

SDK 提供了完整的测试示例文件，位于 `examples/` 目录：

```bash
examples/
├── pay.php              # 支付下单测试
├── query_refund.php     # 订单查询与退款测试
├── transfer.php         # 转账功能测试
├── profit_sharing.php   # 分账功能测试
├── account.php          # 账户管理测试
├── merchant.php         # 商户管理测试
└── notify.php           # 回调通知处理
```

### 运行测试

1. 修改 `examples/pay.php` 中的配置参数
2. 执行测试命令：

```bash
# Windows (phpstudy_pro)
D:\phpstudy_pro\Extensions\php\php8.2.9nts\php.exe examples\pay.php

# Linux/Mac
php examples/pay.php
```

### 测试环境切换

**测试环境（沙箱）**:
```php
$isSandbox = true;
```

**正式环境**:
```php
$isSandbox = false;
```

## 文档链接

- [接口格式定义](https://doc.3ypay.com/doc-8005015)
- [加签验签说明](https://doc.3ypay.com/doc-8005019)
- [参数说明](https://doc.3ypay.com/doc-8005023)
- [加解签Demo](https://doc.3ypay.com/doc-8117681)
- [完整API文档](https://doc.3ypay.com/)
## License

MIT