文档名称 支付相关接口文档V1.1.1
文档类型 接口文档
说明 超级前台提供收银台，支付接口文档

目录

1 概述

1.1请求规则

规则名称 描述
请求地址 https://xxxxx/super_cloud
请求方式 GET/POST
参数格式 application/json
字符编码 统一采用UTF-8字符编码

1.2安全控制

系统采用如下方式保证产品需求方平台的安全性
1、平台各接口支持HTTPS协议。
2、访问任意接口都需要验证签名才能访问。

2 接口说明

2.1下单

2.1.1接口名

/api/opendata/openpay/unifiedPay

2.1.2功能说明

下单功能

2.1.3请求方式

请求方法: POST
Content-Type: application/json
编码方式: UTF-8

2.1.4请求参数

参数名称 参数类型 是否必须 示例值 描述
userId string 是 oUdulwb0saPji7MF_PpJLDhQ8oYM userToken,由平台携带url参数跳转到到业务页面
number integer 是 1 数量（可默认填1）
officePrice decimal 否 8.00 官方价格（单位元）小数点后两位，不传时默认为支付金额
payAmount decimal 是 7.80 实际支付金额结算价（单位元）小数点后两位
discountAmount decimal 否 7.80 优惠金额
orderNo string 是 DD200824163707000 订单号
notifyUrl string 是 回调地址，支付成功后，通知业务方支付结果
resultPageUrl string 是 支付成功/失败后 跳转页面地址(携带参数：orderNo=xxx&code=SUCCESS/FAIL)
orderTime string 是 2021-11-23 23:59:59 下单时间
productList array 否 产品信息 不参与验签
timestamp long 是 1574651175506 时间戳，以毫秒为单位
sign string 是 签名，详见签名规则
appKey string 是 fwzc8EtxzIfX9Ql3Hmgh

productList结构 不参与验签

参数名称 参数类型 是否必须 示例值 描述
productName string 是 A套餐(2人餐) 商品名称
amount integer 是 2 商品数量
productImg string 是 商品图片地址
productDetail array 否 [{“childProductName”:鸡翅,”amount”:2, “childProductImage”:”https:xxxxx”}] 产品详情，主要是套餐中的子产品
price decimal 是 8.00 结算价格（单位元）小数点后两位
costPrice decimal 否 8.00 成本价格（单位：元）小数点后两位
officialPrice decimal 否 8.00 官方价格（单位：元）小数点后两位

2.1.5返回值

参数名称 参数类型 是否必须 示例值 描述
code integer 是 200 200 为成功，其他为失败
msg string 是 签名错误 返回状态码信息
data object 否 返回结果，状态码为200时返回

data返回值说明

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
url string 是 https://xxxx/xxxxx 支付链接(收银台地址) ，需要业务方跳转

示例：

{
    "code":200,
    "msg":"成功",
    "data":{
        "orderNo":"1232049243039243884",
        "url":"https://xxxx/xxxx"
    }
}

2.1.6异步通知

成功支付后回调（通知的地址为，下单时notifyUrl）

2.1.6.1请求方式

请求方法: POST
Content-Type: application/json
编码方式: UTF-8

2.1.6.2请求参数

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
timestamp long 是 时间戳，毫秒
payStatus string 是 PAYED 表示支付成功 支付状态
orderFee string 是 实付金额，单位分，此参数不参与签名
sign string 是 签名

响应返回示例

{
    "code":200,
    "msg":"SUCCESS"
}

2.2 订单状态查询

2.2.1接口名

/api/opendata/openpay/orderQuery

2.2.2功能说明

提供主动查询订单是否已支付

2.2.3请求方式

请求方法：POST
Content-Type: application/json
编码方式: UTF-8

2.2.4请求参数

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
appKey string 是 fwzc8EtxzIfX9Ql3Hmgh
timestamp long 是 1567074659106 时间戳，毫秒
sign string 是 签名详情可参考（签名规则）

2.2.5返回值

参数名称 参数类型 是否必须 示例值 描述
code integer 是 200 200 为成功，其他为失败
msg string 是 签名错误 返回状态码信息
data object 否 返回结果，状态码为200时返回

data返回值说明

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
orderStatus integer 是 1 订单是否已经支付 1-已支付 0-未支付

示例

{
    "code":200,
    "msg":"成功",
    "data":{
        "orderNo":"DD200824163707000",
        "orderStatus":1
    }
}

2.3 申请退款接口

2.3.1接口名

/api/opendata/openpay/refund

2.3.2功能说明

发起申请退款请求

2.3.3请求方式

请求方法: POST
Content-Type: application/JSON
编码方式: UTF-8

2.3.4请求参数

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
refundNo string 是 退款订单号
refundPrice decimal 是 7.80 退款金额（单位元）小数点后两位
refundReason string 是 退款原因
notifyUrl string 是 退款回调通知地址
appKey string 是 fwzc8EtxzIfX9Ql3Hmgh
timestamp long 是 1567074659106 时间戳，毫秒
sign string 是 签名详情可参考（签名规则）

2.3.5返回值

参数名称 参数类型 是否必须 示例值 描述
code integer 是 200 200 为成功，其他为失败
msg string 是 签名错误 返回状态码信息
data object 否 返回结果，状态码为200时返回

data返回值说明

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
refundTime string 是 2021-11-24 10:50:17 响应时间

示例

{
    "code":200,
    "msg": "成功",
    "data": {
        "orderNo": "K201027202701877",
        "refundTime": "2021-11-24 10:50:17"
    }
}

2.3.6异步通知

成功退款后回调（通知的地址为，退款申请时notifyUrl）

2.3.6.1请求方式

请求方法: POST
Content-Type: application/json
编码方式: UTF-8

2.3.6.2请求参数

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
refundNo string 是 退款订单号
isPart string 是 是否部分退款 0代表全款，1代表部分退款
timestamp string 是 时间戳，毫秒
payStatus string 是 REFUNDED 表示退款成功 退款状态
sign string 是 签名

响应返回示例

{
    "code":200,
    "msg":"SUCCESS"
}

2.4 退款单查询

2.4.1接口名

/api/opendata/openpay/refundQuery

2.4.2功能说明

退款单查询

2.4.3请求方式

请求方法: POST
Content-Type: application/JSON
编码方式: UTF-8

2.4.4请求参数

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
refundNo string 是 退款订单号
appKey string 是 fwzc8EtxzIfX9Ql3Hmgh
timestamp long 是 1567074659106 时间戳，毫秒
sign string 是 签名详情可参考（签名规则）

2.4.5返回值

参数名称 参数类型 是否必须 示例值 描述
code integer 是 200 200 为成功，其他为失败
msg string 是 签名错误 返回状态码信息
data object 否 返回结果，状态码为200时返回

data返回值说明

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
refundNo string 是 退款订单号
orderStatus integer 1 订单是否已经退款 1-已退款 0-未退款

示例

{
    "code":200,
    "msg":"成功",
    "data":{
            "orderNo":"MC200824163707000",
            "refundNo":"MC200824163707000",
            "orderStatus":1
    }
}

2.5 关闭订单

2.5.1接口名

/api/opendata/openpay/closeOrder

2.5.2功能说明

关闭订单

2.5.3请求方式

请求方法: POST
Content-Type: application/JSON
编码方式: UTF-8

2.5.4请求参数

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
appKey string 是 fwzc8EtxzIfX9Ql3Hmgh
timestamp long 是 1567074659106 时间戳，毫秒
sign string 是 签名详情可参考（签名规则）

2.5.5返回值

示例

{
    "code": 200,
    "msg": "关单成功"
}

2.6余额查询

2.6.1接口名

/api/opendata/openpay/getBalance

2.6.2功能说明

下单功能

2.6.3请求方式

请求方法: POST
Content-Type: application/json
编码方式: UTF-8

2.6.4请求参数

参数名称 参数类型 是否必须 示例值 描述
userId string 是 oUdulwb0saPji7MF_PpJLDhQ8oYM userToken,由平台携带url参数跳转到到业务页面
orgId int 是 123 由平台线下提供，平台项目ID
timestamp long 是 1574651175506 时间戳，以毫秒为单位
sign string 是 签名，详见签名规则
appKey string 是 fwzc8EtxzIfX9Ql3Hmgh

2.6.5返回值

参数名称 参数类型 是否必须 示例值 描述
code integer 是 200 200 为成功，其他为失败
msg string 是 签名错误 返回状态码信息
data object 否 返回结果，状态码为200时返回

data返回值说明

参数名称 参数类型 是否必须 示例值 描述
totalBalance decimal 是 88.21 账户总余额（包括补贴账户及个人充值账户）
subsidyBalance decimal 是 80.21 补贴账户
rechargeBalance decimal 是 8 个人充值账户

示例：

{
    "code":200,
    "msg":"成功",
    "data":{
        "totalBalance":88.21,
                "subsidyBalance":80.21,
                "rechargeBalance":8
    }
}

3 签名规则

3.1签名介绍

调用接口都需要携带签名，服务端会根据请求参数，对签名进行校验，签名不合法的请求将会被拒绝。

3.2签名方法

以接口/api/opendata/openpay/orderQuery为例

请求的参数如下

  • appKey：fwzc8EtxzIfX9Ql3Hmgh

  • timestamp：1680580829000

  • orderNo：ZZGX20230404173443981

平台方提供的密钥secretKey为77f44bf82004154f763a2eb4fa096487a017fe9c

  1. 将请求参数中除appKey、sign外的多个非空键值对(为空的参数不参与签名),根据键按照字典序排序,并按照key1=value1&key2=value2...的格式拼成一个字符串。
string str = "orderNo=ZZGX20230404173443981&timestamp=1680580829000";
  1. 将secretKey拼接在第一步中排序后的字符串后面得到待签名字符串。
string signTemp = str + "&secretKey=77f44bf82004154f763a2eb4fa096487a017fe9c";
//orderNo=ZZGX20230404173443981&timestamp=1680580829000&secretKey=77f44bf82004154f763a2eb4fa096487a017fe9c
  1. 对待签名字符串求MD5摘要并转为大写即为sign：4CC2EB02383141C666F14D0EE681FB7A

需要注意以下规则

  1. 请求参数的值为空值(null)则不参与签名，请求参数的值为空字符串(“”)则会参与签名
  2. 参数名区分大小写
  3. appKey、sign参数不参与签名

4 响应码

响应码 响应说明
200 请求通过
503 签名错误
9999 系统异常
500 请求异常
文档更新时间: 2025-03-27 14:30   作者：吴长福