PHP SDK文档

1. 概述

LakShinePaySDK.php 是专为LakShine支付平台开发的PHP SDK，提供了简单易用的接口封装，支持统一下单、订单查询、退款等核心功能。

1.1 特性

支持PHP 7.0及以上版本
MD5签名算法
统一下单接口
订单查询接口
退款接口
异步通知处理
完整的错误处理
详细的代码注释

1.2 系统要求

PHP >= 7.0
cURL扩展
JSON扩展
OpenSSL扩展

2. 安装配置

2.1 下载SDK

从官网下载 LakShinePaySDK.php 文件，或使用以下命令：

wget https://api.lakshine.com/sdk/LakShinePaySDK.php

2.2 引入SDK

<?php
require_once 'LakShinePaySDK.php';
?>
            

2.3 初始化配置

<?php
// 创建SDK实例
$sdk = new LakShinePaySDK([
    'mchid' => '123456789',           // 商户ID
    'secretkey' => 'your_secret_key', // 商户密钥
    'api_url' => 'https://api.lakshine.com', // API地址
    'timeout' => 30                   // 请求超时时间（秒）
]);
?>
            

3. 基础使用

3.1 统一下单

<?php
// 统一下单
$orderData = [
    'out_trade_no' => 'TEST' . date('YmdHis') . rand(1000, 9999),
    'amount' => '100.00',
    'channel' => 'lakshine',
    'notify_url' => 'https://your-domain.com/notify',
    'return_url' => 'https://your-domain.com/return',
    'body' => '商品购买'
];

try {
    $result = $sdk->unifiedOrder($orderData);
    if ($result['result_code'] === 'SUCCESS') {
        $payUrl = $result['charge']['credential']['charge_url'];
        echo "支付链接：" . $payUrl;
    } else {
        echo "下单失败：" . $result['result_msg'];
    }
} catch (Exception $e) {
    echo "异常：" . $e->getMessage();
}
?>
            

3.2 订单查询

<?php
// 查询订单
try {
    $result = $sdk->queryOrder('TEST202501050001');
    if ($result['result_code'] === 'SUCCESS') {
        $status = $result['charge']['status'];
        echo "订单状态：" . $status;
    }
} catch (Exception $e) {
    echo "查询失败：" . $e->getMessage();
}
?>
            

3.3 申请退款

<?php
// 申请退款
$refundData = [
    'out_trade_no' => 'TEST202501050001',
    'out_refund_no' => 'REFUND' . date('YmdHis') . rand(1000, 9999),
    'refund_amount' => '50.00'
];

try {
    $result = $sdk->refund($refundData);
    if ($result['result_code'] === 'SUCCESS') {
        echo "退款申请成功";
    } else {
        echo "退款失败：" . $result['result_msg'];
    }
} catch (Exception $e) {
    echo "退款异常：" . $e->getMessage();
}
?>
            

4. API参考

4.1 构造函数

public function __construct(array $config)

参数：

参数名	类型	必填	说明
mchid	string	是	商户ID
secretkey	string	是	商户密钥
api_url	string	否	API地址，默认：https://api.lakshine.com
timeout	int	否	请求超时时间，默认：30秒

4.2 统一下单方法

public function unifiedOrder(array $orderData): array

参数：

参数名	类型	必填	说明
out_trade_no	string	是	商户订单号
amount	string	是	支付金额
channel	string	是	支付渠道
notify_url	string	是	异步通知地址
return_url	string	否	同步跳转地址
body	string	否	商品描述

4.3 订单查询方法

public function queryOrder(string $outTradeNo): array

4.4 退款方法

public function refund(array $refundData): array

4.5 验证签名方法

public function verifySign(array $data, string $sign): bool

5. 完整示例

5.1 完整的支付流程

<?php
require_once 'LakShinePaySDK.php';

// 初始化SDK
$sdk = new LakShinePaySDK([
    'mchid' => '123456789',
    'secretkey' => 'your_secret_key',
    'api_url' => 'https://api.lakshine.com'
]);

// 1. 创建订单
$orderData = [
    'out_trade_no' => 'TEST' . date('YmdHis') . rand(1000, 9999),
    'amount' => '100.00',
    'channel' => 'lakshine',
    'notify_url' => 'https://your-domain.com/notify',
    'return_url' => 'https://your-domain.com/return',
    'body' => '商品购买'
];

try {
    $result = $sdk->unifiedOrder($orderData);
    if ($result['result_code'] === 'SUCCESS') {
        $payUrl = $result['charge']['credential']['charge_url'];
        // 跳转到支付页面
        header('Location: ' . $payUrl);
        exit;
    } else {
        echo "下单失败：" . $result['result_msg'];
    }
} catch (Exception $e) {
    echo "系统异常：" . $e->getMessage();
}
?>
            

5.2 异步通知处理

<?php
require_once 'LakShinePaySDK.php';

// 初始化SDK
$sdk = new LakShinePaySDK([
    'mchid' => '123456789',
    'secretkey' => 'your_secret_key'
]);

// 接收异步通知
$notifyData = $_POST;

// 验证签名
if ($sdk->verifySign($notifyData, $notifyData['sign'])) {
    // 签名验证通过
    if ($notifyData['status'] === 'SUCCESS') {
        // 支付成功，更新订单状态
        $outTradeNo = $notifyData['out_trade_no'];
        $tradeNo = $notifyData['trade_no'];
        $amount = $notifyData['amount'];
        
        // 这里添加您的业务逻辑
        updateOrderStatus($outTradeNo, 'paid', $tradeNo, $amount);
        
        echo 'SUCCESS'; // 返回成功标识
    } else {
        echo 'FAIL';
    }
} else {
    // 签名验证失败
    echo 'FAIL';
}

function updateOrderStatus($outTradeNo, $status, $tradeNo, $amount) {
    // 更新订单状态的业务逻辑
    // 这里需要根据您的数据库结构来实现
}
?>
            

6. 错误处理

6.1 异常类型

异常类型	说明	处理方式
InvalidArgumentException	参数错误	检查传入参数
RuntimeException	运行时错误	检查网络连接和API地址
Exception	通用异常	查看异常信息

6.2 错误处理示例

<?php
try {
    $result = $sdk->unifiedOrder($orderData);
    // 处理成功结果
} catch (InvalidArgumentException $e) {
    // 参数错误
    error_log("参数错误：" . $e->getMessage());
    echo "参数错误，请检查输入";
} catch (RuntimeException $e) {
    // 运行时错误
    error_log("运行时错误：" . $e->getMessage());
    echo "系统繁忙，请稍后重试";
} catch (Exception $e) {
    // 其他异常
    error_log("未知错误：" . $e->getMessage());
    echo "系统异常，请联系技术支持";
}
?>
            

7. 常见问题

7.1 签名验证失败

问题：调用接口时返回签名错误
解决方案：

检查商户密钥是否正确
确认参数排序是否正确
验证MD5算法实现

7.2 异步通知接收不到

问题：支付成功后没有收到异步通知
解决方案：

检查notify_url是否可访问
确认服务器防火墙设置
验证网络连接

7.3 订单状态不同步

问题：支付成功但订单状态未更新
解决方案：

检查异步通知处理逻辑
确认数据库更新操作
验证订单号匹配

目录