3ypay/sdk

3ypay (汇联支付) PHP SDK - 统一支付、查询、退款、转账、分账等

dev-master 2026-03-06 13:18 UTC

Requires

• php: ^7.4 || ^8.0
• ext-json: *
• ext-openssl: *
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^9.0

MIT

• 3YPay Team

• payment
• sdk
• wechat
• alipay
• unionpay
• 3ypay

README

V1.0.0 内部测试版本，仅供参考使用。请务必参照对接文档进行对接

1. 3ypay (汇联支付) PHP SDK，支持统一支付、交易查询、退款、转账、分账等功能。
2. 具体参数说明，请查看 API 文档。
3. 请务必对照文档进行配置，并确保代码正确运行。

安装

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

composer require 3ypay/sdk

方式二：手动安装

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

composer install

环境要求

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

快速开始

1. 初始化 SDK

<?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 开放平台 申请
• privateKey: RSA2 私钥，用于请求签名
• platformPublicKey: 平台 RSA2 公钥，用于响应验签
• sandbox: 测试环境设为 true，生产环境设为 false

3. 订单号规范

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

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

功能模块

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

支付宝扫码支付

$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'];
}

微信扫码支付

$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 支付（小程序/公众号）

$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 支付（小程序）

$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,
    '[e-mail]'  // 买家支付宝账号（必填）
);

微信 APP 支付

$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
);

银联支付

$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
);

统一下单（自定义参数）

$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' => '附加数据',
]);

交易查询

根据支付订单号查询：

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

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

根据商户订单号查询：

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

退款

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

退款查询

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

2. 转账 (Transfer)

// 转账到银行卡
$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',
    '[e-mail]',
    '张三'
);

// 转账查询
$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)

// 请求分账
$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)

// 账户余额查询
$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)

// 商户进件
$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',
]);

回调通知验证

// 接收回调
$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: 沙箱 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 证书

curl.cainfo = "D:\phpstudy_pro\Extensions\cacert.pem"

解决方案 B（仅开发环境）: 临时禁用 SSL 验证 修改 src/Client.php 第 44 行：

'verify' => false,

2. 订单号长度不合法

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

解决方案: 使用推荐的订单号格式

$mchOrderNo = 'ORDER_' . date('YmdHis') . '_' . rand(1000, 9999);
// 示例：ORDER_20260306203431_9516 (共 24 位)

3. 商户未认证

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

解决方案:

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

测试说明

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

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

运行测试

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

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

# Linux/Mac
php examples/pay.php

测试环境切换

测试环境（沙箱）:

$isSandbox = true;

正式环境:

$isSandbox = false;

文档链接

• 接口格式定义
• 加签验签说明
• 参数说明
• 加解签Demo
• 完整API文档

  License

MIT