蓝鲸易支付BLUE WHALE PAY
企业级聚合支付服务平台· 银行级加密· 7×24 小时稳定运行

开发文档

面向商户服务端的支付接入指南,涵盖 V2(RSA2 签名)与 V1(MD5 兼容)两套接口:下单支付、异步通知、订单查询、退款、关闭订单、商户信息与代付。

V2 · RSA2 推荐 V1 · MD5 兼容 JSON · UTF-8
下载 V2 SDK(RSA2) 下载 V1 SDK(MD5)

接入前请先注册商户并完成实名认证,在「用户中心 → 个人资料」获取商户 ID、密钥与 RSA 公钥。

01

接入流程

  1. STEP 1

    注册与认证

    注册商户账号并完成实名认证,在「用户中心 → 个人资料」获取商户 ID(pid);使用 RSA2 接口请在该页面生成商户 RSA 密钥对,妥善保存商户私钥,并记录平台公钥。

  2. STEP 2

    配置回调域名

    在用户中心添加并授权支付域名,准备好服务端的异步通知地址 notify_url 与页面跳转地址 return_url,两个地址必须可从公网访问。

  3. STEP 3

    服务端下单

    按签名规则对请求参数签名,调用统一下单接口(V2)或跳转支付接口创建订单,依据返回的支付参数引导用户完成付款。

  4. STEP 4

    接收通知并发货

    用户付款后平台向 notify_url 发送异步通知,请验签、核对金额与订单状态,处理成功后输出 success;页面跳转 return_url 仅作展示,不作为发货依据。

新接入商户请直接使用 V2(RSA2) 接口;V1(MD5)接口仅为兼容历史商户保留。

02

协议规则

项目说明
接口基址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/createsubmit.php / mapi.php
签名方式RSA2(SHA256WithRSA)MD5
时间戳请求与返回均携带 timestamp无
成功状态码code = 0code = 1
返回支付参数pay_type + pay_infopayurl / qrcode / urlscheme 三选一
异步通知验签平台公钥 RSA2 验签商户密钥 MD5 验签
扩展能力退款查询、订单关闭、代付、商户信息等基础下单、查询、退款
03

RSA2 签名规则

密钥获取

登录用户中心,进入「个人资料」页面,点击【生成商户 RSA 密钥对】。对接时:

  • 商户私钥:用于对请求参数签名,请写入服务端代码并妥善保管,切勿泄露到前端或客户端;
  • 平台公钥:用于验证接口返回数据与异步通知的签名。

签名步骤

  1. 获取所有请求参数,剔除 sign、sign_type 字段以及值为空的参数(数组、文件等非字符串参数不参与签名);
  2. 按照参数名 ASCII 码从小到大排序(字典序);
  3. 将排序后的参数依次拼接为 k=v 并用 & 连接,参数值不做 URL 编码,得到待签名字符串;
  4. 使用商户私钥对待签名字符串计算 RSA 签名(SHA256WithRSA),将签名结果 Base64 编码后作为 sign 传入。

验签步骤

  1. 按上述相同规则,用接口返回(或异步通知)的非空参数重新拼装待签名字符串;
  2. 使用平台公钥,以 sign(Base64 解码)对待签名字符串执行 RSA2 验签,通过后再处理业务。
PHP · 生成 / 验证签名
// 生成待签名字符串:字典序排序,剔除 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 秒。

04

统一下单(V2)

服务端后端发起支付请求,按支付场景返回跳转地址、二维码链接或 JSAPI / APP 支付参数。

POST https://ljepay.com/api.php?s=pay/create

兼容入口:POST https://ljepay.com/mapi.php(共用同一套下单参数,不强制时间戳,成功返回 code=1,建议新商户使用 api.php?s=pay/create)。

请求参数

字段名变量名必填类型示例值说明
商户 IDpid是Int10001用户中心获取
支付方式type条件Stringwxpay见支付方式列表;被扫支付可不传,由授权码自动识别
接口类型method否Stringwebweb 通用网页 / jump 仅跳转 / jsapi 公众号生活号 / app APP 支付 / scan 付款码被扫,默认按 device 自动判断
设备类型device否Stringpc见设备类型列表,默认 pc;传 jump 时仅返回支付跳转地址
商户订单号out_trade_no是String202610130001商户系统内唯一,仅允许字母、数字、点、下划线、中划线与竖线
异步通知地址notify_url是Stringhttps://www.example.com/notify.php服务器异步通知,需完成域名授权
跳转通知地址return_url否Stringhttps://www.example.com/return.php支付完成后的页面跳转地址
商品名称name是StringVIP 会员超过 127 字节自动截断
商品金额money是String1.00单位:元,最多两位小数,须大于 0
用户 IP 地址clientip是String192.168.1.100用户实际发起支付的 IP
用户 Openidsub_openid条件StringoXXXXXXXXmethod=jsapi 时必传
应用 AppIdsub_appid否Stringwx1234567890jsapi 支付使用的公众号 / 小程序 AppId
是否小程序is_applet否Int1jsapi 场景下传 1 表示微信小程序
被扫授权码auth_code条件String134567890123456789method=scan 时必传,付款码 / 支付条码内容
业务扩展参数param否String—支付成功后原样返回,没有请留空
自定义通道 IDchannel_id否Int12对应进件商户通道 ID,未进件请勿传
买家身份证号cert_no否String110101199001011234限制指定买家,仅支付宝官方接口支持
买家真实姓名cert_name否String张三限制指定买家,仅支付宝官方接口支持
买家最小年龄min_age否Int18限制买家年龄,仅支付宝官方接口支持
站点名称sitename否String蓝鲸商城支付页展示的站点名称
当前时间戳timestamp是String178120607210 位秒级时间戳,误差不超过 300 秒
签名类型sign_type是StringRSARSA2 接口固定传 RSA
签名字符串sign是StringK8d9xQ==按RSA2 签名规则生成,Base64 编码

返回参数

字段名变量名类型说明
返回状态码codeInt0 为成功,其它值为失败,失败原因见 msg
错误信息msgString失败时返回原因
平台订单号trade_noString平台生成的支付订单号
发起支付类型pay_typeString见支付结果类型
发起支付参数pay_infoString随 pay_type 不同,为跳转地址、二维码链接或 JSON 支付参数
当前时间戳timestampString平台返回时间戳
签名类型sign_typeString固定 RSA
签名字符串signString平台对返回参数的 RSA2 签名,请用平台公钥验签
JSON · 返回示例(扫码支付)
{
  "code": 0,
  "trade_no": "2026101314300012345",
  "pay_type": "qrcode",
  "pay_info": "weixin://wxpay/bizpayurl?pr=04IPMKM",
  "timestamp": "1781206072",
  "sign_type": "RSA",
  "sign": "K8d9xQM7...Base64..."
}
PHP · 请求示例
$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']
}
05

页面跳转支付

用于用户在浏览器前台直接发起支付:构造 form 表单(推荐 POST)或 URL 跳转到平台,支付完成后跳回 return_url。

POST GET https://ljepay.com/submit.php
字段名变量名必填类型示例值说明
商户 IDpid是Int10001—
支付方式type否Stringalipay不传则跳转平台收银台,由用户选择支付方式
商户订单号out_trade_no是String202610130001商户系统内唯一
异步通知地址notify_url是Stringhttps://www.example.com/notify.php服务器异步通知地址
跳转通知地址return_url是Stringhttps://www.example.com/return.php页面跳转通知地址
商品名称name是StringVIP 会员超过 127 字节自动截断
商品金额money是String1.00单位:元,最多两位小数
业务扩展参数param否String—支付后原样返回
自定义通道 IDchannel_id否Int12对应进件商户通道 ID,未进件请勿传
买家身份证号cert_no否String—仅支付宝官方接口支持
买家真实姓名cert_name否String张三仅支付宝官方接口支持
买家最小年龄min_age否Int18仅支付宝官方接口支持
签名类型sign_type是StringRSARSA 商户传 RSA;V1 MD5 商户传 MD5
签名字符串sign是String—按签名算法生成
HTML · 表单跳转示例
<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>
06

支付结果通知

通知分为两种:服务器异步通知(notify_url,发货依据)与页面跳转通知(return_url,仅展示)。平台以 GET 方式携带参数请求通知地址。

字段名变量名必填类型说明
商户 IDpid是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下单时传入则原样返回
当前时间戳timestampV2StringV2 订单返回,10 位秒级
签名类型sign_type是StringV2 订单为 RSA,V1 订单为 MD5
签名字符串sign是String按对应版本规则验签
  • 商户服务端接收并处理成功后,必须向平台直接输出纯文本 success(不含 HTML 标签);
  • 平台未识别到 success 时,会按 1 分钟、3 分钟、20 分钟、1 小时、2 小时的节奏重复通知;
  • 通知可能重复送达,请以 out_trade_no 做幂等处理;务必先验签、再核对金额与订单状态后发货;
  • 页面跳转 return_url 不带任何发货语义,用户关闭浏览器时可能不发生跳转。
PHP · 异步通知处理(V2 / RSA2)
// 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';
07

查询订单(V2)

POST 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。

08

退款与退款查询(V2)

需平台开启商户自助退款,并在商户权限中开通「订单退款 API」后才可调用;部分支付通道要求退款金额与原订单金额一致。

申请退款

POST 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。

查询退款

POST https://ljepay.com/api.php?s=pay/refundquery

业务参数(二选一):refund_no(平台退款单号)或 out_refund_no(商户退款单号)。返回字段含退款单号、关联订单号、退款金额、status、申请与完成时间等。

09

关闭订单(V2)

POST https://ljepay.com/api.php?s=pay/close

用于关闭尚未支付的订单,业务参数 trade_no 与 out_trade_no 二选一。成功返回 code=0、msg=订单关闭成功。

10

商户信息与订单列表(V2)

查询商户信息

POST https://ljepay.com/api.php?s=merchant/info

仅需公共参数(pid、timestamp、sign_type、sign)。返回字段:

变量名类型说明
codeInt0 为成功
pidInt商户 ID
statusInt商户状态,1 正常 / 0 封禁
pay_statusInt收款权限状态
settle_statusInt结算权限状态
moneyString商户可用余额
settle_typeInt结算方式:1 支付宝 / 2 微信 / 3 QQ / 4 银行卡
settle_accountString结算账号
settle_nameString结算户名
order_numInt历史订单总数
order_num_todayInt今日成功订单数
order_num_lastdayInt昨日成功订单数
order_money_todayString今日成功订单金额
order_money_lastdayString昨日成功订单金额

批量查询订单

POST https://ljepay.com/api.php?s=merchant/orders
字段名变量名必填类型说明
返回数量limit否Int默认 10,最大 50
偏移量offset否Int默认 0,按订单倒序分页
订单状态status否Int1 已支付 / 0 未支付,不传则全部返回

成功返回 code=0 与 data 订单数组,元素字段与查询订单返回一致。

11

代付接口(V2)

代付(企业付款 / 转账到账)需平台开通功能并为商户单独授权,所有接口均使用 V2 公共参数与 RSA2 签名。

提交代付

POST 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/querybiz_no 或 out_biz_no 二选一status(1 成功 / 2 失败 / 其它处理中)、amount、cost_money、paydate、errmsg
转账凭证api.php?s=transfer/proofbiz_no 或 out_biz_no 二选一转账凭证信息
可转余额与费率api.php?s=transfer/balance仅公共参数available_money、transfer_rate
12

V1 兼容接口(MD5)

V1 接口使用商户密钥进行 MD5 签名,无需时间戳,成功状态码为 code=1(退款接口为 code=0)。新商户无需使用本节。

MD5 签名算法

  1. 将所有参数按参数名 ASCII 码从小到大排序,sign、sign_type 与空值不参与签名;
  2. 按 a=b&c=d&e=f 拼接为 URL 键值对,参数值不做 URL 编码;
  3. 在拼接字符串末尾直接拼接商户密钥 KEY 后做 MD5,结果取 32 位小写:sign = md5(待签名字符串 . KEY)。

V1 接口一览

功能方式地址说明
页面跳转支付POST/GETsubmit.php参数同页面跳转支付,sign_type=MD5,type 不传进入收银台
API 接口支付POSTmapi.php比跳转支付额外必传 clientip,可选 device;成功返回 code=1、trade_no 及 payurl / qrcode / urlscheme 三选一
查询商户信息GETapi.php?act=query参数 pid、key(商户密钥明文)
查询单个订单GETapi.php?act=order参数 pid、key、trade_no / out_trade_no 二选一
批量查询订单GETapi.php?act=orders参数 pid、key,可选 limit(最大 50)、offset、status
查询结算记录GETapi.php?act=settle参数 pid、key,可选 limit、offset
提交订单退款POSTapi.php?act=refund参数 pid、key、trade_no / out_trade_no、money;需商户开通退款 API,成功 code=0

V1 异步通知字段与 V2 一致,但签名固定为 MD5 且不带 timestamp,使用商户密钥按本节算法验签,处理成功后同样输出 success。已设置为仅 RSA 签名的商户不能调用 V1 接口。

13

支付方式列表

实际可用支付方式以平台通道配置与商户分组权限为准,下表为当前平台已启用的支付方式。

调用值描述
alipay支付宝
wxpay微信支付
qqpayQQ钱包
14

设备类型列表

统一下单接口 device 参数取值,平台据此选择 H5 跳转或扫码等支付形态。

调用值描述
pc电脑浏览器(默认)
mobile手机浏览器
qq手机 QQ 内浏览器
wechat微信内浏览器
alipay支付宝客户端
douyin抖音客户端
app原生 APP 内 WebView
jump仅返回支付跳转 URL(同时强制 method=jump)
15

支付结果类型

V2 统一下单返回的 pay_type 取值及 pay_info 处理方式:

pay_typepay_info 内容与处理方式
jump支付跳转 URL,直接跳转即可
html自动提交的 HTML 表单代码,写入页面后自动跳转
qrcode支付二维码链接,请据此生成二维码供用户扫码
urlscheme微信 / 支付宝小程序或客户端 URL Scheme,使用 JS 跳转发起支付
jsapiJSAPI(公众号 / 生活号)支付参数 JSON,在对应 JS-SDK 中调起支付
appAPP 支付参数 JSON,交由 iOS / 安卓原生 SDK 调起
scan付款码被扫支付结果,支付完成后返回订单信息
wxapp跳转微信小程序支付参数
wxplugin微信小程序插件支付参数
16

错误码说明

code含义处理建议
0V2 接口成功(V1 退款接口同为 0)正常处理业务数据
1V1 下单 / 查询接口成功—
-1业务失败根据 msg 提示处理,如订单不存在、金额不合法等
-2权限或通道错误如商户未开通退款 API、支付通道下单异常,可稍后重试或更换支付方式
-3认证或签名失败检查商户 ID、密钥 / RSA 公钥、签名串拼接规则与参数编码
-4参数错误检查必填参数、时间戳(误差 ≤300 秒)与请求格式
-5接口不存在 / 无此操作核对接口地址与 s 路由(如 pay/create)

所有失败返回均包含 msg 字段描述具体原因,请记录日志便于排查;签名与时间戳类错误不会创建订单,修正参数后可直接重试。

17

SDK 下载

接入联调中如遇签名、通道或结算问题,请登录用户中心联系在线客服或商务支持,提供平台订单号 trade_no 可快速定位。