商户接入接口文档

1. 概述

LakShine支付平台提供统一的支付接口，支持多种支付方式，为商户提供安全、便捷的支付服务。

1.1 接口地址

                生产环境：https://api.lakshine.com/pay/unifiedorder

                测试环境：https://test-api.lakshine.com/pay/unifiedorder

1.2 请求方式

所有接口均采用 POST 方式，Content-Type 为 application/x-www-form-urlencoded

1.3 字符编码

请求和响应均使用 UTF-8 编码

2. 签名算法

所有接口请求都需要进行MD5签名验证，确保数据安全。

2.1 签名步骤

将所有参数按参数名ASCII码从小到大排序
拼接成 key=value 格式，用 & 连接
在字符串末尾加上 &key=商户密钥
对字符串进行MD5加密，得到32位小写签名

2.2 签名示例

// 请求参数
amount=100.00
mchid=123456789
nonce_str=abc123
out_trade_no=TEST202501050001
timestamp=1704412800

// 排序后拼接
amount=100.00&mchid=123456789&nonce_str=abc123&out_trade_no=TEST202501050001×tamp=1704412800&key=your_secret_key

// MD5签名
sign=md5("amount=100.00&mchid=123456789&nonce_str=abc123&out_trade_no=TEST202501050001×tamp=1704412800&key=your_secret_key")
            

3. 统一下单接口

商户通过该接口创建支付订单，获取支付链接或二维码。

3.1 请求参数

参数名	类型	必填	说明
mchid	string	是	商户ID
out_trade_no	string	是	商户订单号，唯一
amount	decimal	是	支付金额，单位：元
channel	string	是	支付渠道：lakshine
notify_url	string	是	异步通知地址
return_url	string	否	同步跳转地址
body	string	否	商品描述
timestamp	int	是	时间戳
nonce_str	string	是	随机字符串
sign	string	是	签名

3.2 响应参数

参数名	类型	说明
result_code	string	结果码：SUCCESS/FAIL
result_msg	string	结果信息
charge	object	支付信息
charge.credential	object	支付凭证
charge.credential.charge_url	string	支付链接

3.3 请求示例

POST /pay/unifiedorder HTTP/1.1
Host: api.lakshine.com
Content-Type: application/x-www-form-urlencoded

mchid=123456789&out_trade_no=TEST202501050001&amount=100.00&channel=lakshine¬ify_url=https://your-domain.com/notify&return_url=https://your-domain.com/return&body=商品购买×tamp=1704412800&nonce_str=abc123&sign=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
            

3.4 响应示例

{
    "result_code": "SUCCESS",
    "result_msg": "下单成功",
    "charge": {
        "credential": {
            "charge_url": "https://pay.lakshine.com/pay/123456789"
        }
    }
}
            

4. 订单查询接口

商户通过该接口查询订单支付状态。

4.1 请求参数

参数名	类型	必填	说明
mchid	string	是	商户ID
out_trade_no	string	是	商户订单号
timestamp	int	是	时间戳
nonce_str	string	是	随机字符串
sign	string	是	签名

5. 退款接口

商户通过该接口对已支付的订单进行退款操作。

5.1 请求参数

参数名	类型	必填	说明
mchid	string	是	商户ID
out_trade_no	string	是	原商户订单号
out_refund_no	string	是	退款订单号
refund_amount	decimal	是	退款金额
timestamp	int	是	时间戳
nonce_str	string	是	随机字符串
sign	string	是	签名

6. 异步通知

支付成功后，平台会向商户配置的notify_url发送异步通知。

6.1 通知参数

参数名	类型	说明
mchid	string	商户ID
out_trade_no	string	商户订单号
trade_no	string	平台订单号
amount	decimal	支付金额
status	string	支付状态：SUCCESS
sign	string	签名

注意：商户收到异步通知后，必须验证签名，并返回"SUCCESS"字符串表示接收成功。

7. 错误码说明

错误码	说明	解决方案
PARAM_ERROR	参数错误	检查请求参数是否完整、正确
SIGN_ERROR	签名错误	检查签名算法和密钥是否正确
ORDER_NOT_EXIST	订单不存在	检查订单号是否正确
ORDER_PAID	订单已支付	订单已完成支付，无需重复操作
INSUFFICIENT_BALANCE	余额不足	检查账户余额

8. 接入示例

8.1 PHP示例

<?php
// 统一下单示例
$params = [
    'mchid' => '123456789',
    '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' => '商品购买',
    'timestamp' => time(),
    'nonce_str' => uniqid()
];

// 生成签名
ksort($params);
$signStr = '';
foreach ($params as $key => $value) {
    $signStr .= $key . '=' . $value . '&';
}
$signStr .= 'key=your_secret_key';
$params['sign'] = md5($signStr);

// 发送请求
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.lakshine.com/pay/unifiedorder');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['result_code'] === 'SUCCESS') {
    echo "支付链接：" . $result['charge']['credential']['charge_url'];
} else {
    echo "下单失败：" . $result['result_msg'];
}
?>
            

8.2 异步通知处理示例

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

// 验证签名
$sign = $notifyData['sign'];
unset($notifyData['sign']);

ksort($notifyData);
$signStr = '';
foreach ($notifyData as $key => $value) {
    $signStr .= $key . '=' . $value . '&';
}
$signStr .= 'key=your_secret_key';
$calculatedSign = md5($signStr);

if ($sign === $calculatedSign) {
    // 签名验证通过，处理业务逻辑
    if ($notifyData['status'] === 'SUCCESS') {
        // 支付成功，更新订单状态
        updateOrderStatus($notifyData['out_trade_no'], 'paid');
    }
    echo 'SUCCESS'; // 返回成功标识
} else {
    echo 'FAIL'; // 签名验证失败
}
?>
            

目录