API 接入文档 · 霖川码支付

接入流程

注册商户账号，登录商户中心
在「接口与回调」中获取 AppId / AppSecret
配置默认异步通知地址（notifyUrl）与同步跳转地址（returnUrl）
调用 /createOrder 创建订单，按签名规则计算 sign
用户扫码支付，监控端推送到平台后触发异步通知
回调地址需输出字符串 success，否则订单标记为「通知失败」，可后台补单

POST创建订单 /createOrder

{网关地址}/createOrder

参数	必填	说明
appId	推荐	商户 AppId。传入后使用商户密钥签名并归属该商户；不传则走旧版平台直连模式
payId	是	商户自定义订单号，同一商户下不可重复
type	是	支付方式：1 = 微信，2 = 支付宝
price	是	订单金额，单位元，必须大于 0，如 10.00
sign	是	签名，规则见下方「签名规则」
param	否	商户自定义透传参数，回调原样返回
isHtml	否	传 1 直接跳转到收银台页面；不传或传 0 返回 JSON
notifyUrl	否	本次订单异步通知地址，不传使用商户中心配置的默认地址
returnUrl	否	本次订单同步跳转地址，不传使用默认地址

成功返回（code=1）data 字段：

{
  "code": 1, "msg": "成功",
  "data": {
    "payId": "202609211001",   // 商户订单号
    "orderId": "20260921...",  // 平台云端订单号
    "payType": 1,              // 支付方式
    "price": "10.00",          // 订单金额
    "reallyPrice": "10.00",    // 实际应支付金额（可能浮动1分）
    "payUrl": "wxp://...",     // 收款码内容，可自行生成二维码
    "isAuto": 1,               // 1=需手动输入金额 0=固定金额码
    "state": 0,
    "timeOut": 5,              // 订单有效期（分钟）
    "date": 1779000000
  }
}

isHtml=1 时浏览器直接跳转 /payPage/pay.html?orderId=云端单号。

POST查询订单状态 /checkOrder

{网关地址}/checkOrder

参数：orderId（云端订单号）。支付成功时 code=1，data 为带签名参数的同步跳转地址；未支付 / 已过期时 code=-1。收银台页面每 1.5 秒轮询该接口。

POST关闭订单 /closeOrder

{网关地址}/closeOrder

参数：orderId、sign。签名规则：sign = md5(orderId + AppSecret)。仅待支付订单可关闭，关闭后占用金额立即释放。

支付结果异步通知

用户支付成功且监控端推送后，平台服务器以 GET 方式请求 notifyUrl，并携带：
payId、param、type、price、reallyPrice、sign
商户服务器验签通过、业务处理成功后，必须向平台输出字符串 success（不带任何 HTML）。输出其他内容时订单将被标记为「通知失败」，可在平台后台手工补单重新通知。

防重处理：同一笔订单可能收到多次通知，请以 payId 做幂等判断。

签名规则

场景	签名串
创建订单	md5(payId + param + type + price + AppSecret)
关闭订单	md5(orderId + AppSecret)
回调 / 同步跳转验签	md5(payId + param + type + price + reallyPrice + AppSecret)

字符串直接拼接，不含任何分隔符；price 使用两位小数字符串；md5 结果为 32 位小写。

PHP 示例代码

1）创建订单

// 商户中心获取
$gateway = 'https://pay.example.com/';
$appId     = 'M20260921000001';
$appSecret = '您的AppSecret';

$param = [
    'appId'  => $appId,
    'payId'  =>'ORDER' . date('YmdHis') . mt_rand(1000, 9999),
    'type'   => 1,                // 1微信 2支付宝
    'price'  => '10.00',
    'param'  => 'goods_123',
    'isHtml' => 1,
    'notifyUrl' => 'https://your.site/notify.php',
];
$param['sign'] = md5(
    $param['payId'] . $param['param'] .
    $param['type']  . $param['price'] . $appSecret
);

$ch = curl_init($gateway . 'createOrder');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($param),
    CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);
// isHtml=1 时可直接输出脚本跳转到收银台：
// header('Location: ' . $gateway . 'payPage/pay.html?orderId=' . $res['data']['orderId']);

2）异步通知验签（notify.php）

$appSecret = '您的AppSecret';
$sign = md5(
    $_GET['payId'] . $_GET['param'] . $_GET['type'] .
    $_GET['price'] . $_GET['reallyPrice'] . $appSecret
);
if ($sign !== $_GET['sign']) {
    exit('sign error');
}
// TODO: 校验金额、更新订单状态（注意按 payId 幂等处理）
echo 'success';   // 必须输出 success

兼容彩虹易支付协议（免改造对接）

如果您的站点 / 发卡系统已内置「彩虹易支付 / 易支付」通用支付通道，无需任何改造即可对接本平台：

网关地址	https://您的域名/
商户ID（pid）	即商户中心的 AppId（形如 M20260922130478）
商户密钥	即商户中心的 AppSecret
支付方式	alipay（支付宝）、wxpay（微信）；暂不支持 qqpay

三个标准入口：

入口	说明
/submit.php	网页跳转（GET/POST），302 跳转到本平台收银台，供浏览器直接发起支付
/mapi.php	服务端下单（POST），返回 JSON，payurl 为收银台地址，由商户站点自行跳转
/api.php?act=order	订单查询（GET/POST），返回 status：0 未支付 / 1 已支付

下单公共参数：

参数	必填	说明
pid	是	商户ID，即 AppId
type	是	alipay 或 wxpay
out_trade_no	是	商户订单号，同一商户下重复提交返回原订单（不重复下单）
notify_url	是	异步通知地址（地址本身不要带 ? 查询参数，透传数据请用 param）
return_url	是	支付完成后浏览器同步跳转地址（同样不要带查询参数）
name	是	商品名称，如 9.9福利转盘单
money	是	金额，单位元，大于 0，如 9.96
param	否	透传参数，异步 / 同步回调原样返回
sign	是	签名（规则见下）
sign_type	是	MD5

mapi.php 成功返回示例：

{
  "code": 1,
  "msg": "下单成功",
  "trade_no": "202609220209076575",
  "out_trade_no": "ORDER20260922001",
  "type": "alipay",
  "money": "9.96",
  "payurl": "https://您的域名/payPage/pay.html?orderId=202609220209076575",
  "urlscheme": ""
}

支付成功回调参数（GET 请求 notify_url，同步跳转参数相同）：

pid、trade_no、out_trade_no、type、name、money、realprice、trade_status=TRADE_SUCCESS、sign_type=MD5、sign（有 param 时一并返回）

商户处理成功后必须输出纯字符串 success；同一订单可能多次通知，按 out_trade_no 做幂等。

彩虹标准签名算法（与官方易支付 SDK 完全一致）：

// 1. 剔除 sign、sign_type 以及值为空的参数
// 2. 按参数名 ASCII 升序排序
// 3. 拼接成 a=1&b=2（值不做 urlencode）
// 4. 末尾直接拼接商户密钥后 md5（32位小写）
function epaySign(array $params, $key) {
    unset($params['sign'], $params['sign_type']);
    $params = array_filter($params, function ($v) { return $v !== '' && $v !== null; });
    ksort($params);
    return md5(urldecode(http_build_query($params)) . $key);
}

查询接口签名同样使用上述算法，参与参数为实际发送的 act、pid、out_trade_no（或 trade_no）等。