支付相关接口文档

目录

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

2.1.2功能说明

直接下单扣款,无收银台

2.1.3请求方式

请求方法: POST

Content-Type: application/json

编码方式: UTF-8

2.1.4请求参数

参数名称 参数类型 是否必须 示例值 描述
userId string 是 oUdulwb0saPji7MF_PpJLDhQ8oYM 卡号,码、手机号,用户ID,根据userIdType来具体定义值。
userIdType string 是 CARD_NO(卡号)、AUTH_CODE(云卡二维码/微信支付宝付款码)、MOBILE(手机号) 用户ID类型
orgId int 是 123 项目ID 由平台线下提供
merchantId int 是 123 商户ID 由平台线下提供
officialPrice decimal 否 8.00 官方价格(单位元),保留小数点后两位,不传时默认为支付金额
payAmount decimal 是 7.80 实际支付金额/结算价(单位元),保留小数点后两位
discountAmount decimal 否 0.20 优惠金额
orderNo string(40) 是 MC200824163707000 订单号
notifyUrl string 是 回调地址
orderTime string 是 2021-11-23 23:59:59 下单时间,格式yyyy-MM-dd HH:mm:ss
timestamp long 是 1574651175506 时间戳,以毫秒为单位。
sign string 是 签名,详见签名规则
appKey string 是 由平台方提供
orderDesc string(250) 否 订单描述
payCode string 否 CASH_PAY CENTER_WALLET-饭卡支付（不填时默认饭卡支付，且根据userIdType=authcode码类型来自动判断是饭卡或微信、支付宝支付）； CASH_PAY-现金记账支付（线下已支付或记账支付） ;THIRD_BALANCE-福利余额

2.1.5返回值

参数名称 参数类型 是否必须 示例值 描述
code int 是 200 响应状态码
msg string 是 签名错误 返回状态码信息
data object 是 返回结果
code说明
code状态码 说明
200 支付成功
201 支付中
500 支付失败
data返回值说明
参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 订单号
resultCode string 是 SUCCESS 支付状态码
resultCode支付状态码
支付状态码 说明
SUCCESS 支付成功
USERPAYING 支付中
FAIL 支付失败
ORDERPAID 已支付
ORDERCLOSED 订单已关闭
NOTEXIST 用户不存在
NOTENOUGH 余额不足
EXPIRED 云卡码已过期
示例
{
  "code": 200,
  "msg":"支付成功",
  "data":{
    "orderNo":"1232049243039243884",
    "resultCode": "SUCCESS"
  }
}
---
{
  "code": 201,
  "msg":"支付中",
  "data":{
    "orderNo":"1232049243039243884",
    "resultCode": "USERPAYING"
  }
}
---
{
  "code": 500,
  "msg":"支付失败，订单已支付",
  "data":{
    "orderNo":"1232049243039243884",
    "resultCode": "ORDERPAID"
  }
}
---
{
  "code": 500,
  "msg":"支付失败，订单已关闭",
  "data":{
    "orderNo":"1232049243039243884",
    "resultCode": "ORDERCLOSED"
  }
}

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 是 MC201027202701877 订单号
orgId int 是 123 项目ID 由平台线下提供
timestamp long 是 1567074659106 时间戳,以毫秒为单位。
appKey string 是 由平台方提供
sign string 是 AC8F94DFA73856D2A35A8287ACD493A 签名详情可参考(签名规则)

2.2.5返回值

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

data返回值说明

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

示例

{
  "code":200,
  "msg":"成功",
  "data":{
    "orderNo":"MC200824163707000",
    "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 是 MC201027202701877 订单号
refundNo string 是 退款订单号
orgId int 是 123 项目ID 由平台线下提供
refundPrice decimal 是 7.80 退款金额(单位元)小数点后两位
notifyUrl string 是 退款回调
timestamp long 是 1567074659106 时间戳,以毫秒为单位。
sign string 是 AC8F94DFA73856D2A35A8287ACD493A 签名详情可参考(签名规则)
refundReason string(20) 是 下单失败 申请退款原因
appKey string 是 由平台方提供

2.3.5返回值

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

data返回值说明

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

示例

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

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 是 MC200402172419636 订单号
refundNo string 是 MC200402172419636 退款订单号
orgId int 是 123 项目ID 由平台线下提供
appKey string 是 由平台方提供
timestamp long 是 1567074659106 时间戳,以毫秒为单位
sign string 是 AC8F94DFA73856D2A35A8287ACD493A 签名详情可参考(签名规则)

2.4.5返回值

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

data返回值说明

参数名称 参数类型 是否必须 示例值 描述
orderNo string 是 MC200824163707000 订单号
refundNo string 是 MC200824163707000 退款订单号
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 是 MC200402172419636 订单号
orgId int 是 123 项目ID 由平台线下提供
appKey string 是 由平台方提供
timestamp long 是 1567074659106 时间戳,以毫秒为单位
sign string 是 AC8F94DFA73856D2A35A8287ACD493A 签名详情可参考(签名规则)

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 卡号,码、手机号,用户ID,根据userIdType来具体定义值。
userIdType string 是 CARD_NO(卡号)、AUTH_CODE(云卡二维码)、MOBILE(手机号) 用户ID类型
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返回值说明

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

示例：

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

2.7 获取云卡付款码

2.7.1接口名

/api/opendata/openpay/getUserAuthCode

2.7.2功能说明

根据用户获取云卡码，用于支付或用户信息查询验证。

2.7.3请求方式

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

2.7.4请求参数

参数名称 参数类型 是否必须 示例值 描述
userId string 是 oUdulwb0saPji7MF_PpJLDhQ8oYM 卡号,码、手机号,用户ID,根据userIdType来具体定义值。
userIdType string 是 CARD_NO(卡号)、MOBILE(手机号) 用户ID类型
orgId int 是 123 由平台线下提供
timestamp Long 是 1574651175506 时间戳，以毫秒为单位
sign string 是 签名，详见签名规则
appKey string 是 fwzc8EtxzIfX9Ql3Hmgh

2.7.5返回值

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

data返回值说明

参数名称 参数类型 是否必须 示例值 描述
authCode string 是 88.21 云卡码
expireTime long 是 120 过期时间 单位秒

示例：

{
    "code":200,
    "msg":"成功",
    "data":{
        "authCode":"abcdedfghidgek",
        "expireTime":120
    }
}

2.8根据云卡付款码获取用户信息

2.8.1接口名

/api/opendata/openinfo/cloud_card/identify

2.8.2功能说明

根据云卡付款码获取用户信息

2.8.3请求方式

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

2.8.4请求参数

参数名称 参数类型 是否必须 示例值 描述
code string 是 oUdulwb0saPji7MF_PpJLDhQ8oYM 云卡码 /实体卡号
timestamp Long 是 1574651175506 时间戳，以毫秒为单位
sign string 是 签名，详见签名规则
appKey string 是 fwzc8EtxzIfX9Ql3Hmgh

2.8.5返回值

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

data返回值说明

参数名称 参数类型 是否必须 示例值 描述
orgId Integer 是 615 项目id
orgName String 是 航空大厦 项目名称
virtId Integer 是 1 企业id
virtName String 是 超级前台 企业名称
userName String 是 名字 用户名
userMobile String 是 15211112222 手机号码
userId Integer 是 1 用户id

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参数不参与签名

    响应码

响应码 响应说明
200 请求成功
503 签名错误
9999 系统异常
500 请求失败
文档更新时间: 2025-04-07 15:31   作者：吴长福