版本1.0.0

开始之前

1️⃣ 基本信息

项目内容
BaseURLhttps://pay.clickpay.lol
响应格式application/json
时间单位Unix 时间戳（单位：秒）
数组排序时间升序，越早越前

2️⃣ 通用状态码

HTTP Code含义
200请求成功
400请求参数或头信息错误
401拒绝访问
403签名错误
404请求地址不存在
500系统异常
503业务失败（需查看返回业务错误码）

3️⃣ 错误返回格式

{
    "code": "错误码",
    "message": "错误信息"
}

4️⃣ 接口限流与超时

项目规则
代收接口限流按商户限流，每秒 150 次请求，突发容量 150 次
代付接口限流按商户限流，每秒 60 次请求，突发容量 60 次
代收接口超时60 秒
代付接口超时60 秒
商户回调超时连接、读取、写入超时均为 10 秒

代收或代付请求长时间未响应时，请先按异常处理并联系技术支持提供请求与订单信息；订单最终状态以异步回调为准。

5️⃣ 安全机制 - 签名校验规则（Signature）

📌 通用说明

  • 所有请求需在 Header 带上签名信息。
  • 签名参数名：Signature
  • Header 名称大小写不敏感；Base64 签名值区分大小写，不可改变。
  • 商户：用私钥签名。
  • 平台：返回数据用私钥签名，商户用平台公钥验签。

摘要统一使用小写十六进制 SHA-512，RSA 使用 PKCS#1 v1.5。JSON 只序列化一次，签名和发送使用同一份 UTF-8 字节；不能对收到的回调 body 排序、格式化或重新序列化后再验签。完整密钥格式、错误日志和各语言实现见代码示例中的“统一规则”。

📌 签名算法流程

POST / PUT 请求
1️⃣ Body 内容 SHA512 -> 摘要A
2️⃣ 拼接 path + 摘要A + 时间戳 -> 文本B
3️⃣ 用 RSA 私钥，对 文本B 做 SHA512withRSA 签名
GET / DELETE 请求
1️⃣ 无 body，摘要A 为空字符串
2️⃣ 拼接 path + 摘要A + 时间戳 -> 文本B
3️⃣ 用 RSA 私钥，对 文本B 做 SHA512withRSA 签名

📌 Header 必填项

Header 名描述
Timestamp当前时间戳（秒）
Merchant-Code商户编号
Signature签名值

6️⃣ 接口示例：下单接口

请求地址

POST /v1/merchant/pay

Header 示例

HeaderValue
Merchant-Code003
Timestamp1699447297
Signature[签名字符串]

请求参数（JSON Body）

{
    "amount": "2",
    "method": "gee",
    "phone": "1",
    "name": "1",
    "merchantSerialNo": "T1699447296",
    "remark": "1",
    "email": "1"
}

签名过程示例（伪代码）

Step1: SHA512 摘要A
    {"amount":"2","method":"gee",...} -> 摘要A = 7e28...（共128个小写十六进制字符，不含时间戳）

Step2: 拼接
    /v1/merchant/pay + 摘要A + 时间戳
    -> /v1/merchant/pay7e28...1699447297

Step3: RSA 签名
    SHA512WithRSA(拼接结果) -> 签名结果

curl 示例

curl -X POST 'https://pay.clickpay.lol/v1/merchant/pay' -H "Content-Type: application/json" -H "Merchant-Code: 003" -H "Timestamp: 1699447297" -H "Signature: [签名值]" -d '{"amount":"2","method":"gee","phone":"1","name":"1","merchantSerialNo":"T1699447296","remark":"1","email":"1"}'

成功响应

{
    "code": 0,
    "msg": null,
    "sign": "[返回签名]",
    "timestamp": "1699448046",
    "data": {
        "merchantId": "618918202310181957279",
        "merchantSerialNo": "T1699447296",
        "method": "gee",
        "amount": 2,
        "transactionId": "6189182023110820540519",
        "payUrl": "https://openapi.kypays.com/pix/6189182023110820540519",
        "fee": "0.42000000",
        "status": "10",
        "payData": {"qrcode":"000201..."}
    }
}

7️⃣ 接口示例：查询余额

请求地址

GET /v1/merchant/account

Header 示例

HeaderValue
Merchant-Code003
Timestamp1699447297
Signature[签名字符串]

签名过程示例（伪代码）

Step1: 参数拼接（GET 无参数时，paramStr 为空字符串）
  paramStr = ""

Step2: 拼接签名内容
  /v1/merchant/account + paramStr + Timestamp
  -> /v1/merchant/account1699447297

Step3: 使用 SHA512WithRSA 生成签名
  Signature = SHA512WithRSA(拼接结果)

curl 示例

curl -X GET 'https://pay.clickpay.lol/v1/merchant/account' \
  -H "Merchant-Code: 003" \
  -H "Timestamp: 1699447297" \
  -H "Signature: [签名值]"

成功响应

{
    "code": 0,
    "sign": "[返回签名]",
    "timestamp": "1699448200",
    "data": {
        "currency": "[currency]",
        "id": "263940537239867393",
        "memberId": "618918202501161501465",
        "memberCode": "UPITEST",
        "memberName": "UPITEST",
        "accountType": "11",
        "cash": 112.0,
        "freeze": 0.0,
        "security": 0.0,
        "unSettlement": 0.0,
        "credit": 0.0,
        "createTime": "2025-01-16 15:01:46"
    }
}

8️⃣ 平台回调签名规则 ✅（重点）

⚠️ 与请求签名不同，回调签名不包含 path，仅拼接摘要 + 时间戳

📌 签名算法（平台 → 商户）

1️⃣ 计算回调 Body 的 SHA512 -> 摘要A
2️⃣ 拼接 摘要A + 时间戳（Header 中）
3️⃣ 使用平台 RSA 私钥，对拼接结果做 SHA512withRSA 签名

📌 Header 示例

HeaderValue
Timestamp1699447297
Signature[签名值]

📌 Body 示例

{
    "merchantId": "618918202310181957279",
    "merchantSerialNo": "T1699447296",
    "method": "gee",
    "amount": 2,
    "transactionId": "6189182023110820540519",
    "payUrl": "https://openapi.kypays.com/pix/6189182023110820540519",
    "fee": "0.42000000",
    "status": "10"
}

📌 签名过程示例

Step1: SHA512 摘要A
    -> 7e28...

Step2: 拼接
    7e28... + 1699447297

Step3: 签名
    SHA512withRSA(拼接结果) -> 签名值

📌 商户验签流程

商户收到回调后：

  1. 获取回调 JSON Body，按 UTF-8 字符串格式进行 SHA512 摘要。
  2. 拼接：摘要 + Timestamp（Header）。
  3. 使用平台公钥、SHA512withRSA 验证签名。

9️⃣ RSA 公私钥示例

完整可运行的 Python 回调验签样例 包含测试平台公钥、原始 Body、Timestamp、Signature 和预期结果，无需私钥即可验证。

样例使用 2048 位测试密钥，签名 Base64 解码后为 256 字节；这不是线上平台公钥。实际接入请使用对应商户后台的平台公钥，不要使用商户公钥。若实际公钥为 1024 位，而签名解码后为 256 字节，两者不匹配，修改密钥格式无法解决。

🔟 签名示例对照表

步骤示例值
SHA512 摘要A7e28...（共128个小写十六进制字符）
RSA 签名结果HpPa41g0aK4zP...==

11. 代码示例

Java 接入说明

欲了解详细的 SDK 集成方法及示例代码，请参考 Java 示例文档。

PHP 接入说明

欲了解详细的 SDK 集成方法及示例代码，请参考 PHP 示例文档。

C# 接入说明

欲了解详细的 SDK 集成方法及示例代码，请参考 C# 示例文档。

Go 接入说明

欲了解详细的 SDK 集成方法及示例代码，请参考 Go 示例文档。

Python 接入说明

欲了解详细的 SDK 集成方法及示例代码，请参考 Python 示例文档。

Node.js 接入说明

欲了解详细的 SDK 集成方法及示例代码，请参考 Node.js 示例文档。

公开 API 参数

枚举定义

订单状态

参数名 (status)

代收

状态描述
00待匹配商户
10待支付
11支付中
12支付超时
20支付完成
30支付退款
31支付失败

代付

状态描述
00待匹配商户
10待处理
11待支付
12代付中
20代付完成
30代付退款
31代付失败
手续费类型

参数名 (feeType)

手续费类型描述
0从代付金额内扣
1从余额内扣

代收支付方式

参数名 (method)

支付方式
QR
TRANSFER

代付支付方式

参数名 (method)

支付方式描述
BANK银行转账
WALLET钱包支付

代收

下单

POST /v1/merchant/pay

请求

{
  "amount": "100",
  "method": "QR",
  "phone": null,
  "name": "1",
  "merchantSerialNo": "T1699447296",
  "remark": "1",
  "email": null
}

参数列表

参数名参数类型可空介绍
amountstring否金额
methodstring否见枚举中 支付方式
phonestring是手机号码
namestring否名称
merchantSerialNostring否商户订单号
remarkstring是备注
descriptionstring否描述
emailstring是邮箱
notifyUrlstring是回调地址，当此值不为空，则回调此地址，否则回调后台填入的回调地址
redirectUrlstring是跳转地址，当此值不为空，支付完成后用户将跳转到此地址
directConnectboolean是是否直连，true=直连，false=非直连（默认false）

响应

{
    "code": 0,
    "sign": "glOvHa8zstiAG6/6fZ/fhECYH64j4rdFj9uHW9qks5Vvdke1imEvmeMcImDrb1l+EDFYrGV/ovJ5SuEnmPZtmy1Gyeh1f3NlL9Y5N/PKvlMZn9CrGEmRHwn2hzFuNuYiYCHbYwPr2e5llMpojGF/ySNvUvPJXD7G3ouLQdSSIUE=",
    "timestamp": "1754387547",
    "data": {
        "merchantCode": "M",
        "currency": "myr",
        "merchantSerialNo": "74769685-b602-4a85-a306-1c64aa627e22",
        "method": "QR",
        "amount": 100,
        "transactionId": "61891820250821190735390021",
        "payUrl": "https://cashier2.clickpay.lol/pay/v1/myr/1",
        "fee": 10.0,
        "status": "10"
    }
}

参数列表

参数名参数类型可空介绍
codeint否见错误码
msgstring是错误消息
signstring是签名
timestampstring是时间戳
dataobject是订单数据

data

参数名参数类型可空介绍
merchantSerialNostring否商户订单号
methodstring否支付方式
amountstring否金额
transactionIdstring否平台订单号
payUrlstring是支付地址
statusstring否见枚举中 订单状态，需检查订单状态，因网络波动可能导致拉单失败
feestring否手续费

查询代收订单

POST /v1/merchant/pay/order/info

请求

{
  "transactionId": "61891820250719160658208575",
  "merchantSerialNo": "T1699447296",
}

参数列表

参数名参数类型可空介绍
transactionIdString是平台订单号，两者至少传一个
merchantSerialNoString是商户订单号

响应

{
  "code": 0,
  "sign": "DKeoiWNFEByMQsRFix2dC7f7jA8GGXQOBTYVsRpmYtJXMA/Vd5j06M74Q23215kwjuuzBWRfiiQbZDKNq/kJRz1WMpsomyCL/TKsqzAhMX7JBXWCGYLql5WS0sIG2pNB4mSxKUVtOxqErEUf8V4e1ozrQBHfdtydDueegGK+rjUaQGLSM/KzPygwDN6X0n/egN1rYQwJ6yfafwAIDVH7cW3hrnzG0b2UToC6SaxWsxCRnGh2JUsHgT+xfrzjwtROSq311tuxLlNtu4nFTacyvk7xlYsF+NZKgeMe5RAzvFU1eAxncuqqqCrOyIGiOGZHjFlJmCmoiHmNb2bxgYieDg==",
  "timestamp": "1737088697",
  "data": {
    "merchantId": "618918202501161501465",
    "merchantSerialNo": "T1737088694387",
    "method": "[method]",
    "amount": 200,
    "orderAmount": 200,
    "transactionId": "61891820250117123815588",
    "payUrl": "https://h5.simplypay.vip/payment/d1bab78392a941d4b4f570dbd0728303?cashUrl=https://pay.wepaytm.xyz/upi/checkout/4I6w",
    "fee": 20.0,
    "status": "10"
  }
}

参数列表

参数名参数类型可空介绍
codeint否见错误码
msgstring是错误消息
signstring是签名
timestampstring是时间戳
dataobject是订单数据

data

参数名参数类型可空介绍
merchantSerialNostring否商户订单号
methodstring否支付方式
amountstring否实付金额
orderAmountstring否订单金额
transactionIdstring否平台订单号
payUrlstring否支付地址
payDatastring是支付内容
statusstring否见枚举中 订单状态
feestring否手续费
channelBankSerialNostring是银行流水号
messagestring是失败原因

代收异步通知

POST 商户设置的代收回调地址

请求

HEAHDERS

参数描述
Signature签名
Timestamp时间戳

BODY

{
  "transactionId": "2",
  "amount": "1",
  "orderAmount": "1",
  "currency": "",
  "method": "gee",
  "merchantSerialNo": "T1699447296",
  "status": "20",
  "payUrl": "http://",
  "fee": "0.1"
}

参数列表

参数名参数类型可空介绍
merchantSerialNostring否商户订单号
methodstring否支付方式
currencystring否币种
amountstring否实付金额
orderAmountstring否订单金额
transactionIdstring否平台订单号
payUrlstring否支付地址
statusstring否见枚举中 订单状态
feestring否手续费
channelBankSerialNostring是银行流水号
messagestring是失败原因

响应

SUCCESS

商户需返回 SUCCESS。首次通知会立即发送；失败后每 60 秒检查并重试，累计最多通知 10 次。

代付

下单

POST /v1/merchant/payout

请求

{
  "bankCode": "affinbank",
  "bankName": "AffinBank",
  "amount": "2",
  "method": "BANK",
  "bankCard": "1",
  "accountEmail": null,
  "accountMobile": null,
  "accountName": "1",
  "merchantSerialNo": "T1701344062",
  "bankName": "1",
  "remark": "1",
  "feeType": "1"
}

参数列表

参数名参数类型可空介绍
amountstring否金额
methodstring否见枚举中 支付方式
bankCodestring否银行编号，见 银行列表
bankCardstring否钱包或银行提款账号
accountMobilestring是手机号码
accountEmailstring是邮箱
accountNamestring否账户名称
bankNamestring否银行名称,可为固定值
merchantSerialNostring否商户订单号
remarkstring是备注
feeTypestring否见枚举中 手续费类型
notifyUrlstring是回调地址，当此值不为空，则回调此地址，否则回调后台填入的回调地址

响应

{
  "code": 0,
  "msg": null,
  "sign": "jTY5Z021R2J/ixsi1t6P4+sH0XoZ4La4YMEFTYe5MlxoEn5s4xcRwv4oZAM5Nk/+lqWyVSRCpKbqzCsyAFo27duJ+MxvzCyIweDSV1tDnyQ42j8IhaAoo61bSVHbmMS2UFMX0wCpiyFLyE0VsAza3hsqYk2Ad0RK043xsasyOrP3PA0x2LLdbY3XauW/Lh9U6VJ6yJyL646inPQ1WmahtZr2bWiL/ueTephTdv/JljwzphyJ3gnrm4a0F9lgMXQX8eborvMhhEQBPYYhpq6trxZ4nOmDQuTx/rHK3WlgTm19VY/IqxZtRcs368qQVe+gFuF3pgyjB4+M9bR5npRQ7w==",
  "timestamp": "1701344063",
  "data": {
    "merchantId": "618918202310181957279",
    "merchantSerialNo": "T1701344062",
    "method": "BANK",
    "amount": 2,
    "transactionId": "618918202311301934237",
    "fee": "10.20000000",
    "status": "10"
  }
}

参数列表

参数名参数类型可空介绍
codeint否见错误码
msgstring是错误消息
signstring是签名
timestampstring是时间戳
dataobject是订单数据

data

参数名参数类型可空介绍
merchantSerialNostring否商户订单号
methodstring否支付方式
amountstring否金额
transactionIdstring否平台订单号
statusstring否见枚举中 订单状态
feestring否手续费

查询代付订单

POST /v1/merchant/payout/order/info

请求

{
  "transactionId": "61891820250719160658208575",
  "merchantSerialNo": "T1699447296",
}

参数列表

参数名参数类型可空介绍
transactionIdString是平台订单号，两者至少传一个
merchantSerialNoString是商户订单号

响应

{
  "code": 0,
  "msg": null,
  "sign": "dZMsjIJd5JrH660JZVKmc3XTwnNOV9WxvvMcuMqIMmbdDXjYUXENL7vshZU965ilkBniBVs2MJEkpz3irB6CaiT7oCY/HirQXrzOrF4csxeBz00sr0fZr+Mv0lWRSgS4CS8ppMB9IYkwuzp8c7gEsRVIV/DaEX3nUdwCPRM1rqKK3M2QvRUvZYHuhof0ewfMRDs5CwTS5s8WL63z2wzChsM0Op5bidG8+Xfdzw8s9x0cphwa4kY8YG4tPfqJy7tcEi0JJerImjGfUyRWX8xR0dU9krwOyKCL5oh+y5eCnF4yKO5BLvQ9RHdz5vZxZc+nkfuXghmN4KmtZzj/Rr/PPw==",
  "timestamp": "1701350818",
  "data": {
    "merchantId": "618918202310181957279",
    "merchantSerialNo": "T1701348703",
    "method": "BANK",
    "amount": 2.0,
    "transactionId": "618918202311302051438",
    "fee": "10.20000000",
    "status": "10"
  }
}

参数列表

参数名参数类型可空介绍
codeint否见错误码
msgstring是错误消息
signstring是签名
timestampstring是时间戳
dataobject是订单数据

data

参数名参数类型可空介绍
merchantSerialNostring否商户订单号
methodstring否支付方式
amountstring否金额
transactionIdstring否平台订单号
statusstring否见枚举中 订单状态
feestring否手续费
channelBankSerialNostring是银行流水号
messagestring是失败原因

代付异步通知

POST 商户设置的代付回调地址

请求

HEAHDERS

参数描述
Signature签名
Timestamp时间戳

BODY

{
  "transactionId": "2",
  "amount": "1",
  "method": "BANK",
  "currency": "",
  "merchantSerialNo": "T1699447296",
  "status": "20",
  "fee": "0.1"
}

参数列表

参数名参数类型可空介绍
merchantSerialNostring否商户订单号
methodstring否支付方式
currencystring否币种
amountstring否金额
transactionIdstring否平台订单号
statusstring否见枚举中 订单状态
feestring否手续费
channelBankSerialNostring是银行流水号
messagestring是失败原因

响应

SUCCESS

商户需返回 SUCCESS。首次通知会立即发送；失败后每 60 秒检查并重试，累计最多通知 10 次。

查询余额

GET /v1/merchant/account

响应

{
  "code": 0,
  "sign": "C3i5JNPU7KLXOM8tWlbJM9pPmeHJ2ciE60VbTJBbfDhK+5hUEDOeqa32yYUX9m7hIgrNIj12Y8SNKctSxB5pw9BVUr2FzDrEb0DY8ppSuQ20KieLXX2xyxXmEAh288I1ikHlO36eWr7u/Plpi/3FEMnLGtHd8ma5T/hz86XIY41a7VwJUvEhwpihASUd4fYtqSRoI+9bFjuC6d92yfpyXo+i/M43lezLSbhOBJnj1pDjF3iBPZVbszOPIK+tsbZjdWPP+SjT59lCMjKtkCAtY/tO7/NQB69Yz/LrS3ar7Z1/Qzo+GYdikCqpi+oCDDZjVgE9IQRuw25NCm+yo5v9hw==",
  "timestamp": "1737090710",
  "data": {
    "currency": "[currency]",
    "id": "263940537239867393",
    "memberId": "618918202501161501465",
    "memberCode": "UPITEST",
    "memberName": "UPITEST",
    "accountType": "11",
    "cash": 112.0,
    "freeze": 0.0,
    "security": 0.0,
    "unSettlement": 0.0,
    "credit": 0.0,
    "createTime": "2025-01-16 15:01:46"
  }
}

参数列表

参数名参数类型可空介绍
codeint否见错误码
msgstring是错误消息
signstring是签名
timestampstring是时间戳
dataobject是余额数据

data

参数名参数类型可空介绍
currencystring否币种
cashstring否现金户
freezestring否冻结户
unSettlementstring否待结算户

银行列表

Bank CodeBank Name
affinbankAffinBank
agrobankAgroBank
alliancebankAlliance Bank
ambankAmBank
bimbBank Islam Malaysia
bsnBSN
cimbCIMB
hongleongbankHong Leong Bank
maybankMaybank
mbsbMBSB
publicbankPublic Bank
rhbRHB
uob_myUOB Malaysia
bankrakyatBank Rakyat
ocbc_myOCBC Bank
hsbcHSBC

钱包列表

Wallet CodeWallet Name
touchngoTouch 'n Go

错误代码列表

错误码描述
0成功
400请求参数错误
403请求签名不正常
1000用户余额不足
500服务器内部错误，请联系管理员
9999未知异常
9000参数不合法
9002未授权访问
9008重复请求
8000商户已被冻结
8001商户不支持该支付方式
8003本次请求的支付方式或金额不受支持。请按文档填写 method，注意大小写，前后不要带空格；核对 amount 是否符合已开通业务的要求。确认无误后，请联系客服。
最近更新:
Contributors: aa, dell, Copilot, aaa