CKPay Cloud API 文档

所有 API 使用 HTTP 协议，请求方式支持 GET 与 POST，响应为 JSON 或表单。

Base URL：https://your-domain.com
字符编码：UTF-8
金额单位：元（两位小数，如 1.00）

1. 概述

CKPay Cloud 提供统一的支付网关服务，商户通过 API 创建订单后跳转到收银台页面完成支付。支付完成后系统自动回调商户的异步通知地址。

支持签名算法：MD5、HmacSHA256（默认推荐）

2. 签名规则

2.1 HmacSHA256 签名（推荐）

排除 sign 字段与空值
按参数名字母升序排列
拼接为 key1=value1&key2=value2 字符串
使用 HmacSHA256(key) 对字符串签名
结果转小写即为签名值

2.2 签名示例（PHP）

function sign($params, $key) {
    unset($params['sign']);
    foreach ($params as $k => $v) {
        if ($v === '' || $v === null) unset($params[$k]);
    }
    ksort($params);
    $str = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
    return hash_hmac('sha256', $str, $key);
}

$params = [
    'mno'          => 'M0001',
    'out_trade_no' => 'ORDER_001',
    'total_fee'    => '1.00',
    'subject'      => '示例订单',
    'notify_url'   => 'https://example.com/notify',
];
$params['sign'] = sign($params, 'YOUR_SHA256_KEY');
$params['sign_type'] = 'HmacSHA256';

3. 创建订单

URL：POST /api/pay/create

响应示例：

{
    "code": 0,
    "msg": "ok",
    "trade_no": "CK20261007123456ABCDEF",
    "pay_url": "https://your-domain.com/pay/CK20261007123456ABCDEF",
    "expire_at": "2026-10-07 14:05:00",
    "exist": false
}

请求参数

参数	类型	必填	说明
mno	String	必填	商户号
out_trade_no	String	选填	商户订单号（幂等键，不传自动生成）
total_fee	Decimal	必填	金额（元，两位小数）
subject	String	选填	订单标题（最长 128 字符）
body	String	选填	订单描述（最长 512 字符）
notify_url	String	选填	异步通知地址（覆盖商户默认）
return_url	String	选填	同步回调地址
attach	String	选填	附加数据（回调时原样返回）
timeout	Int	选填	超时秒数（默认 1800）
channel_code	String	选填	指定渠道编码
sign_type	String	选填	签名算法，默认 HmacSHA256
sign	String	必填	签名值

4. 异步通知

支付成功后，系统自动 POST 到商户 notify_url。

回调响应：商户收到通知后需原样返回 success 字符串，否则视为失败。

重试策略：失败后按 1m, 5m, 15m, 30m, 1h 间隔重试，最多 5 次。

回调参数

参数	说明
mno	商户号
trade_no	平台订单号
out_trade_no	商户订单号
total_fee	金额
status	状态（1 已支付）
paid_at	支付时间
attach	附加数据
sign	签名值

商户验签示例

$data = $_POST;
$sign = $data['sign'];
unset($data['sign']);
ksort($data);
$str = http_build_query($data, '', '&', PHP_QUERY_RFC3986);
$expected = hash_hmac('sha256', $str, 'YOUR_KEY');
if (hash_equals(strtolower($expected), strtolower($sign))) {
    // 处理业务
    echo 'success';
} else {
    echo 'fail';
}

5. 订单查询

URL：POST /api/pay/query

请求参数：mno + out_trade_no 或 trade_no + sign

响应示例：

{
    "code": 0,
    "msg": "ok",
    "data": {
        "trade_no": "CK20261007123456ABCDEF",
        "out_trade_no": "ORDER_001",
        "total_fee": "1.00",
        "status": 1,
        "subject": "示例订单",
        "paid_at": "2026-10-07 12:05:30",
        "refund_fee": "0.00",
        "remark": "",
        "sign": "abc123..."
    }
}

6. 退款

URL：POST /api/pay/refund

请求参数

参数	类型	必填	说明
mno	String	是	商户号
out_trade_no	String	是	商户订单号
refund_no	String	是	退款单号（幂等键）
refund_fee	Decimal	否	退款金额，默认全额
reason	String	否	退款原因
sign	String	是	签名

7. 错误码

code	说明
0	成功
1	通用错误
400	参数错误
401	签名验证失败
403	禁止访问
404	资源不存在
429	请求过于频繁
500	服务器错误

8. 快速接入示例（PHP）

// 创建订单
$params = [
    'mno'          => 'M0001',
    'out_trade_no' => 'ORDER_' . time(),
    'total_fee'    => '9.99',
    'subject'      => '订阅服务',
    'notify_url'   => 'https://example.com/api/notify',
];
$params['sign'] = sign($params, 'YOUR_KEY');
$params['sign_type'] = 'HmacSHA256';

$resp = json_decode(file_get_contents('https://gateway.example.com/api/pay/create?' . http_build_query($params), false), true);
if ($resp['code'] === 0) {
    header('Location: ' . $resp['pay_url']);
    exit;
}