开发文档
面向商户服务端的支付接入指南,涵盖 V2(RSA2 签名)与 V1(MD5 兼容)两套接口:下单支付、异步通知、订单查询、退款、关闭订单、商户信息与代付。
接入流程
-
STEP 1
注册与认证
注册商户账号并完成实名认证,在「用户中心 → 个人资料」获取商户 ID(pid);使用 RSA2 接口请在该页面生成商户 RSA 密钥对,妥善保存商户私钥,并记录平台公钥。
-
STEP 2
配置回调域名
在用户中心添加并授权支付域名,准备好服务端的异步通知地址 notify_url 与页面跳转地址 return_url,两个地址必须可从公网访问。
-
STEP 3
服务端下单
按签名规则对请求参数签名,调用统一下单接口(V2)或跳转支付接口创建订单,依据返回的支付参数引导用户完成付款。
-
STEP 4
接收通知并发货
用户付款后平台向 notify_url 发送异步通知,请验签、核对金额与订单状态,处理成功后输出 success;页面跳转 return_url 仅作展示,不作为发货依据。
新接入商户请直接使用 V2(RSA2) 接口;V1(MD5)接口仅为兼容历史商户保留。
协议规则
| 项目 | 说明 |
|---|---|
| 接口基址 | https://ljepay.com/ |
| 请求数据格式 | application/x-www-form-urlencoded |
| 返回数据格式 | JSON(UTF-8 编码) |
| 字符编码 | UTF-8 |
| V2 签名算法 | RSA2(SHA256WithRSA),签名结果 Base64 编码 |
| V1 签名算法 | MD5,32 位小写 |
| 时间戳校验 | V2 接口必传 timestamp(10 位秒级),与服务器时间误差不得超过 300 秒 |
接口版本对照
| 对比项 | V2(推荐) | V1(兼容) |
|---|---|---|
| 下单入口 | api.php?s=pay/create | submit.php / mapi.php |
| 签名方式 | RSA2(SHA256WithRSA) | MD5 |
| 时间戳 | 请求与返回均携带 timestamp | 无 |
| 成功状态码 | code = 0 | code = 1 |
| 返回支付参数 | pay_type + pay_info | payurl / qrcode / urlscheme 三选一 |
| 异步通知验签 | 平台公钥 RSA2 验签 | 商户密钥 MD5 验签 |
| 扩展能力 | 退款查询、订单关闭、代付、商户信息等 | 基础下单、查询、退款 |
RSA2 签名规则
密钥获取
登录用户中心,进入「个人资料」页面,点击【生成商户 RSA 密钥对】。对接时:
- 商户私钥:用于对请求参数签名,请写入服务端代码并妥善保管,切勿泄露到前端或客户端;
- 平台公钥:用于验证接口返回数据与异步通知的签名。
签名步骤
- 获取所有请求参数,剔除
sign、sign_type字段以及值为空的参数(数组、文件等非字符串参数不参与签名); - 按照参数名 ASCII 码从小到大排序(字典序);
- 将排序后的参数依次拼接为
k=v并用&连接,参数值不做 URL 编码,得到待签名字符串; - 使用商户私钥对待签名字符串计算 RSA 签名(SHA256WithRSA),将签名结果 Base64 编码后作为
sign传入。
验签步骤
- 按上述相同规则,用接口返回(或异步通知)的非空参数重新拼装待签名字符串;
- 使用平台公钥,以
sign(Base64 解码)对待签名字符串执行 RSA2 验签,通过后再处理业务。
// 生成待签名字符串:字典序排序,剔除 sign、sign_type 与空值
function lj_build_sign_str(array $params) {
ksort($params);
$pairs = array();
foreach ($params as $k => $v) {
if ($k === 'sign' || $k === 'sign_type' || $v === '' || $v === null || is_array($v)) continue;
$pairs[] = $k . '=' . $v;
}
return implode('&', $pairs);
}
// 用商户私钥生成 RSA2 签名(返回 Base64)
function lj_sign(array $params, $merchantPrivateKey) {
openssl_sign(lj_build_sign_str($params), $sign, $merchantPrivateKey, OPENSSL_ALGO_SHA256);
return base64_encode($sign);
}
// 用平台公钥验证返回或通知签名
function lj_verify(array $params, $signBase64, $platformPublicKey) {
return openssl_verify(
lj_build_sign_str($params),
base64_decode($signBase64),
$platformPublicKey,
OPENSSL_ALGO_SHA256
) === 1;
}
签名校验失败通常由以下原因造成:参数未按字典序排序、空值或 sign/sign_type 参与了签名、参数值被 URL 编码、商户私钥与平台公钥不配对、服务器时间偏差超过 300 秒。
统一下单(V2)
服务端后端发起支付请求,按支付场景返回跳转地址、二维码链接或 JSAPI / APP 支付参数。
https://ljepay.com/api.php?s=pay/create
兼容入口:POST https://ljepay.com/mapi.php(共用同一套下单参数,不强制时间戳,成功返回 code=1,建议新商户使用 api.php?s=pay/create)。
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 说明 |
|---|---|---|---|---|---|
| 商户 ID | pid | 是 | Int | 10001 | 用户中心获取 |
| 支付方式 | type | 条件 | String | wxpay | 见支付方式列表;被扫支付可不传,由授权码自动识别 |
| 接口类型 | method | 否 | String | web | web 通用网页 / jump 仅跳转 / jsapi 公众号生活号 / app APP 支付 / scan 付款码被扫,默认按 device 自动判断 |
| 设备类型 | device | 否 | String | pc | 见设备类型列表,默认 pc;传 jump 时仅返回支付跳转地址 |
| 商户订单号 | out_trade_no | 是 | String | 202610130001 | 商户系统内唯一,仅允许字母、数字、点、下划线、中划线与竖线 |
| 异步通知地址 | notify_url | 是 | String | https://www.example.com/notify.php | 服务器异步通知,需完成域名授权 |
| 跳转通知地址 | return_url | 否 | String | https://www.example.com/return.php | 支付完成后的页面跳转地址 |
| 商品名称 | name | 是 | String | VIP 会员 | 超过 127 字节自动截断 |
| 商品金额 | money | 是 | String | 1.00 | 单位:元,最多两位小数,须大于 0 |
| 用户 IP 地址 | clientip | 是 | String | 192.168.1.100 | 用户实际发起支付的 IP |
| 用户 Openid | sub_openid | 条件 | String | oXXXXXXXX | method=jsapi 时必传 |
| 应用 AppId | sub_appid | 否 | String | wx1234567890 | jsapi 支付使用的公众号 / 小程序 AppId |
| 是否小程序 | is_applet | 否 | Int | 1 | jsapi 场景下传 1 表示微信小程序 |
| 被扫授权码 | auth_code | 条件 | String | 134567890123456789 | method=scan 时必传,付款码 / 支付条码内容 |
| 业务扩展参数 | param | 否 | String | — | 支付成功后原样返回,没有请留空 |
| 自定义通道 ID | channel_id | 否 | Int | 12 | 对应进件商户通道 ID,未进件请勿传 |
| 买家身份证号 | cert_no | 否 | String | 110101199001011234 | 限制指定买家,仅支付宝官方接口支持 |
| 买家真实姓名 | cert_name | 否 | String | 张三 | 限制指定买家,仅支付宝官方接口支持 |
| 买家最小年龄 | min_age | 否 | Int | 18 | 限制买家年龄,仅支付宝官方接口支持 |
| 站点名称 | sitename | 否 | String | 蓝鲸商城 | 支付页展示的站点名称 |
| 当前时间戳 | timestamp | 是 | String | 1781206072 | 10 位秒级时间戳,误差不超过 300 秒 |
| 签名类型 | sign_type | 是 | String | RSA | RSA2 接口固定传 RSA |
| 签名字符串 | sign | 是 | String | K8d9xQ== | 按RSA2 签名规则生成,Base64 编码 |
返回参数
| 字段名 | 变量名 | 类型 | 说明 |
|---|---|---|---|
| 返回状态码 | code | Int | 0 为成功,其它值为失败,失败原因见 msg |
| 错误信息 | msg | String | 失败时返回原因 |
| 平台订单号 | trade_no | String | 平台生成的支付订单号 |
| 发起支付类型 | pay_type | String | 见支付结果类型 |
| 发起支付参数 | pay_info | String | 随 pay_type 不同,为跳转地址、二维码链接或 JSON 支付参数 |
| 当前时间戳 | timestamp | String | 平台返回时间戳 |
| 签名类型 | sign_type | String | 固定 RSA |
| 签名字符串 | sign | String | 平台对返回参数的 RSA2 签名,请用平台公钥验签 |
{
"code": 0,
"trade_no": "2026101314300012345",
"pay_type": "qrcode",
"pay_info": "weixin://wxpay/bizpayurl?pr=04IPMKM",
"timestamp": "1781206072",
"sign_type": "RSA",
"sign": "K8d9xQM7...Base64..."
}
$params = array(
'pid' => '10001',
'type' => 'wxpay',
'method' => 'web',
'device' => 'pc',
'out_trade_no' => '202610130001',
'notify_url' => 'https://www.example.com/notify.php',
'return_url' => 'https://www.example.com/return.php',
'name' => 'VIP会员',
'money' => '1.00',
'clientip' => $_SERVER['REMOTE_ADDR'],
'timestamp' => (string)time(),
'sign_type' => 'RSA',
);
$params['sign'] = lj_sign($params, $merchantPrivateKey);
$ch = curl_init('https://ljepay.com/api.php?s=pay/create');
curl_setopt_array($ch, array(
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($params),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
));
$response = json_decode(curl_exec($ch), true);
if ($response['code'] === 0) {
// 按 $response['pay_type'] 处理 $response['pay_info']
}
页面跳转支付
用于用户在浏览器前台直接发起支付:构造 form 表单(推荐 POST)或 URL 跳转到平台,支付完成后跳回 return_url。
https://ljepay.com/submit.php
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 说明 |
|---|---|---|---|---|---|
| 商户 ID | pid | 是 | Int | 10001 | — |
| 支付方式 | type | 否 | String | alipay | 不传则跳转平台收银台,由用户选择支付方式 |
| 商户订单号 | out_trade_no | 是 | String | 202610130001 | 商户系统内唯一 |
| 异步通知地址 | notify_url | 是 | String | https://www.example.com/notify.php | 服务器异步通知地址 |
| 跳转通知地址 | return_url | 是 | String | https://www.example.com/return.php | 页面跳转通知地址 |
| 商品名称 | name | 是 | String | VIP 会员 | 超过 127 字节自动截断 |
| 商品金额 | money | 是 | String | 1.00 | 单位:元,最多两位小数 |
| 业务扩展参数 | param | 否 | String | — | 支付后原样返回 |
| 自定义通道 ID | channel_id | 否 | Int | 12 | 对应进件商户通道 ID,未进件请勿传 |
| 买家身份证号 | cert_no | 否 | String | — | 仅支付宝官方接口支持 |
| 买家真实姓名 | cert_name | 否 | String | 张三 | 仅支付宝官方接口支持 |
| 买家最小年龄 | min_age | 否 | Int | 18 | 仅支付宝官方接口支持 |
| 签名类型 | sign_type | 是 | String | RSA | RSA 商户传 RSA;V1 MD5 商户传 MD5 |
| 签名字符串 | sign | 是 | String | — | 按签名算法生成 |
<form action="https://ljepay.com/submit.php" method="post">
<input type="hidden" name="pid" value="10001">
<input type="hidden" name="type" value="alipay">
<input type="hidden" name="out_trade_no" value="202610130001">
<input type="hidden" name="notify_url" value="https://www.example.com/notify.php">
<input type="hidden" name="return_url" value="https://www.example.com/return.php">
<input type="hidden" name="name" value="VIP会员">
<input type="hidden" name="money" value="1.00">
<input type="hidden" name="sign_type" value="RSA">
<input type="hidden" name="sign" value="<?php echo lj_sign($params, $merchantPrivateKey); ?>">
<button type="submit">立即支付</button>
</form>
支付结果通知
通知分为两种:服务器异步通知(notify_url,发货依据)与页面跳转通知(return_url,仅展示)。平台以 GET 方式携带参数请求通知地址。
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 商户 ID | pid | 是 | Int | — |
| 平台订单号 | trade_no | 是 | String | 蓝鲸易支付订单号 |
| 商户订单号 | out_trade_no | 是 | String | 商户系统内部订单号 |
| 支付方式 | type | 是 | String | 见支付方式列表 |
| 商品名称 | name | 是 | String | — |
| 商品金额 | money | 是 | String | 单位:元 |
| 支付状态 | trade_status | 是 | String | 仅 TRADE_SUCCESS 表示支付成功 |
| 第三方订单号 | api_trade_no | 否 | String | 微信 / 支付宝等渠道方订单号,有值时返回 |
| 支付者账号 | buyer | 否 | String | 有值时返回 |
| 业务扩展参数 | param | 否 | String | 下单时传入则原样返回 |
| 当前时间戳 | timestamp | V2 | String | V2 订单返回,10 位秒级 |
| 签名类型 | sign_type | 是 | String | V2 订单为 RSA,V1 订单为 MD5 |
| 签名字符串 | sign | 是 | String | 按对应版本规则验签 |
- 商户服务端接收并处理成功后,必须向平台直接输出纯文本
success(不含 HTML 标签); - 平台未识别到 success 时,会按 1 分钟、3 分钟、20 分钟、1 小时、2 小时的节奏重复通知;
- 通知可能重复送达,请以
out_trade_no做幂等处理;务必先验签、再核对金额与订单状态后发货; - 页面跳转 return_url 不带任何发货语义,用户关闭浏览器时可能不发生跳转。
// notify.php —— 平台以 GET 方式通知
$params = $_GET;
$sign = isset($params['sign']) ? $params['sign'] : '';
// 使用平台公钥验签
if (!lj_verify($params, $sign, $platformPublicKey)) {
exit('fail');
}
if ($params['trade_status'] !== 'TRADE_SUCCESS') {
exit('success'); // 非成功状态无需发货,同样应答 success
}
// 校验订单存在且金额一致
$order = $db->findOrder($params['out_trade_no']);
if (!$order || bccomp($order['money'], $params['money'], 2) !== 0) {
exit('fail');
}
// 幂等发货
if ($order['status'] !== 1) {
$db->deliverOrder($order);
}
echo 'success';
查询订单(V2)
https://ljepay.com/api.php?s=pay/query
公共参数:pid、timestamp、sign_type=RSA、sign。业务参数二选一:
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 平台订单号 | trade_no | 二选一 | String | 与商户订单号同时传入时以平台订单号为准 |
| 商户订单号 | out_trade_no | 二选一 | String | 下单时使用的商户订单号 |
返回字段(code=0 时):trade_no、out_trade_no、api_trade_no(渠道订单号)、type、pid、name、money、status(1 已支付 / 0 未支付)、refundmoney(已退款金额,有值时返回)、addtime、endtime、buyer、param、clientip,以及 timestamp、sign_type、sign。
退款与退款查询(V2)
需平台开启商户自助退款,并在商户权限中开通「订单退款 API」后才可调用;部分支付通道要求退款金额与原订单金额一致。
申请退款
https://ljepay.com/api.php?s=pay/refund
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 平台订单号 | trade_no | 二选一 | String | 同时传入以平台订单号为准 |
| 商户订单号 | out_trade_no | 二选一 | String | — |
| 退款金额 | money | 是 | String | 单位:元,如 1.50 |
| 商户退款单号 | out_refund_no | 否 | String | 长度大于 5,用于商户侧退款幂等;重复提交已成功的退款单将直接返回原结果 |
成功返回 code=0,含 refund_no(平台退款单号)、money、reducemoney 等字段,失败返回错误码与 msg。
查询退款
https://ljepay.com/api.php?s=pay/refundquery
业务参数(二选一):refund_no(平台退款单号)或 out_refund_no(商户退款单号)。返回字段含退款单号、关联订单号、退款金额、status、申请与完成时间等。
关闭订单(V2)
https://ljepay.com/api.php?s=pay/close
用于关闭尚未支付的订单,业务参数 trade_no 与 out_trade_no 二选一。成功返回 code=0、msg=订单关闭成功。
商户信息与订单列表(V2)
查询商户信息
https://ljepay.com/api.php?s=merchant/info
仅需公共参数(pid、timestamp、sign_type、sign)。返回字段:
| 变量名 | 类型 | 说明 |
|---|---|---|
code | Int | 0 为成功 |
pid | Int | 商户 ID |
status | Int | 商户状态,1 正常 / 0 封禁 |
pay_status | Int | 收款权限状态 |
settle_status | Int | 结算权限状态 |
money | String | 商户可用余额 |
settle_type | Int | 结算方式:1 支付宝 / 2 微信 / 3 QQ / 4 银行卡 |
settle_account | String | 结算账号 |
settle_name | String | 结算户名 |
order_num | Int | 历史订单总数 |
order_num_today | Int | 今日成功订单数 |
order_num_lastday | Int | 昨日成功订单数 |
order_money_today | String | 今日成功订单金额 |
order_money_lastday | String | 昨日成功订单金额 |
批量查询订单
https://ljepay.com/api.php?s=merchant/orders
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 返回数量 | limit | 否 | Int | 默认 10,最大 50 |
| 偏移量 | offset | 否 | Int | 默认 0,按订单倒序分页 |
| 订单状态 | status | 否 | Int | 1 已支付 / 0 未支付,不传则全部返回 |
成功返回 code=0 与 data 订单数组,元素字段与查询订单返回一致。
代付接口(V2)
代付(企业付款 / 转账到账)需平台开通功能并为商户单独授权,所有接口均使用 V2 公共参数与 RSA2 签名。
提交代付
https://ljepay.com/api.php?s=transfer/submit
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 代付方式 | type | 是 | String | 如 alipay、wxpay,以开通的代付通道为准 |
| 商户转账单号 | out_biz_no | 否 | String | 仅允许字母、数字、点、下划线、中划线与竖线;不传由平台生成 |
| 收款账号 | account | 是 | String | 收款人支付宝 / 微信等账号 |
| 收款人姓名 | name | 否 | String | 部分通道必填,以实际开通通道要求为准 |
| 转账金额 | money | 是 | String | 单位:元,大于 0,最多两位小数 |
| 转账备注 | remark | 否 | String | 最多 32 个字符 |
代付相关接口
| 功能 | 接口地址 | 业务参数 | 关键返回 |
|---|---|---|---|
| 代付查询 | api.php?s=transfer/query | biz_no 或 out_biz_no 二选一 | status(1 成功 / 2 失败 / 其它处理中)、amount、cost_money、paydate、errmsg |
| 转账凭证 | api.php?s=transfer/proof | biz_no 或 out_biz_no 二选一 | 转账凭证信息 |
| 可转余额与费率 | api.php?s=transfer/balance | 仅公共参数 | available_money、transfer_rate |
V1 兼容接口(MD5)
V1 接口使用商户密钥进行 MD5 签名,无需时间戳,成功状态码为 code=1(退款接口为 code=0)。新商户无需使用本节。
MD5 签名算法
- 将所有参数按参数名 ASCII 码从小到大排序,
sign、sign_type与空值不参与签名; - 按
a=b&c=d&e=f拼接为 URL 键值对,参数值不做 URL 编码; - 在拼接字符串末尾直接拼接商户密钥 KEY 后做 MD5,结果取 32 位小写:
sign = md5(待签名字符串 . KEY)。
V1 接口一览
| 功能 | 方式 | 地址 | 说明 |
|---|---|---|---|
| 页面跳转支付 | POST/GET | submit.php | 参数同页面跳转支付,sign_type=MD5,type 不传进入收银台 |
| API 接口支付 | POST | mapi.php | 比跳转支付额外必传 clientip,可选 device;成功返回 code=1、trade_no 及 payurl / qrcode / urlscheme 三选一 |
| 查询商户信息 | GET | api.php?act=query | 参数 pid、key(商户密钥明文) |
| 查询单个订单 | GET | api.php?act=order | 参数 pid、key、trade_no / out_trade_no 二选一 |
| 批量查询订单 | GET | api.php?act=orders | 参数 pid、key,可选 limit(最大 50)、offset、status |
| 查询结算记录 | GET | api.php?act=settle | 参数 pid、key,可选 limit、offset |
| 提交订单退款 | POST | api.php?act=refund | 参数 pid、key、trade_no / out_trade_no、money;需商户开通退款 API,成功 code=0 |
V1 异步通知字段与 V2 一致,但签名固定为 MD5 且不带 timestamp,使用商户密钥按本节算法验签,处理成功后同样输出 success。已设置为仅 RSA 签名的商户不能调用 V1 接口。
支付方式列表
实际可用支付方式以平台通道配置与商户分组权限为准,下表为当前平台已启用的支付方式。
| 调用值 | 描述 |
|---|---|
alipay | 支付宝 |
wxpay | 微信支付 |
qqpay | QQ钱包 |
设备类型列表
统一下单接口 device 参数取值,平台据此选择 H5 跳转或扫码等支付形态。
| 调用值 | 描述 |
|---|---|
pc | 电脑浏览器(默认) |
mobile | 手机浏览器 |
qq | 手机 QQ 内浏览器 |
wechat | 微信内浏览器 |
alipay | 支付宝客户端 |
douyin | 抖音客户端 |
app | 原生 APP 内 WebView |
jump | 仅返回支付跳转 URL(同时强制 method=jump) |
支付结果类型
V2 统一下单返回的 pay_type 取值及 pay_info 处理方式:
| pay_type | pay_info 内容与处理方式 |
|---|---|
jump | 支付跳转 URL,直接跳转即可 |
html | 自动提交的 HTML 表单代码,写入页面后自动跳转 |
qrcode | 支付二维码链接,请据此生成二维码供用户扫码 |
urlscheme | 微信 / 支付宝小程序或客户端 URL Scheme,使用 JS 跳转发起支付 |
jsapi | JSAPI(公众号 / 生活号)支付参数 JSON,在对应 JS-SDK 中调起支付 |
app | APP 支付参数 JSON,交由 iOS / 安卓原生 SDK 调起 |
scan | 付款码被扫支付结果,支付完成后返回订单信息 |
wxapp | 跳转微信小程序支付参数 |
wxplugin | 微信小程序插件支付参数 |
错误码说明
| code | 含义 | 处理建议 |
|---|---|---|
0 | V2 接口成功(V1 退款接口同为 0) | 正常处理业务数据 |
1 | V1 下单 / 查询接口成功 | — |
-1 | 业务失败 | 根据 msg 提示处理,如订单不存在、金额不合法等 |
-2 | 权限或通道错误 | 如商户未开通退款 API、支付通道下单异常,可稍后重试或更换支付方式 |
-3 | 认证或签名失败 | 检查商户 ID、密钥 / RSA 公钥、签名串拼接规则与参数编码 |
-4 | 参数错误 | 检查必填参数、时间戳(误差 ≤300 秒)与请求格式 |
-5 | 接口不存在 / 无此操作 | 核对接口地址与 s 路由(如 pay/create) |
所有失败返回均包含 msg 字段描述具体原因,请记录日志便于排查;签名与时间戳类错误不会创建订单,修正参数后可直接重试。
SDK 下载
接入联调中如遇签名、通道或结算问题,请登录用户中心联系在线客服或商务支持,提供平台订单号 trade_no 可快速定位。