开放平台API | 众圈小程序

集成 OpenApi SDK

OpenApi SDK 初始化

private static SDKContext mSDKContext = null;
	
@BeforeClass
public static void setupSDK() {
    try {
        // 初始化SDK
        mSDKContext = new SDKContext(
               "http://localhost:8080/openapi/api/", // API 地址
               "your openid",  // 小程序商户ID
               "your mpid",  // 小程序ID
               "your private key"); // 小程序私钥
       // 设置超时时间
       mSDKContext.setHttpsTimeout(5000, 5000);

    }catch (Exception ex) {
       fail(ex.getMessage());
   }
}

SDK Maven依赖

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <java.version>1.8</java.version>
    <slf4j-version>1.6.3</slf4j-version>
    <swagger-version>1.5.17</swagger-version>
    <jersey.version>2.26</jersey.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.glassfish.jersey.media</groupId>
        <artifactId>jersey-media-json-jackson</artifactId>
        <version>${jersey.version}</version>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jersey.inject</groupId>
        <artifactId>jersey-hk2</artifactId>
        <version>${jersey.version}</version>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jersey.core</groupId>
        <artifactId>jersey-client</artifactId>
        <version>${jersey.version}</version>
    </dependency>

    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>${swagger-version}</version>
    </dependency>

    <dependency>
        <groupId>com.lmspay.openapi</groupId>
        <artifactId>zq-openapi-sdk</artifactId>
        <version>1.0.7</version>
        <scope>system</scope>
        <systemPath>${basedir}/libs/zq-openapi-sdk.1.0.7.jar</systemPath>
    </dependency>
    
    <dependency>
        <groupId>com.txmpay.txmcoreclient</groupId>
        <artifactId>txmcore-client-sdk</artifactId>
        <version>MPORG.1.0.2</version>
        <scope>system</scope>
        <systemPath>${basedir}/libs/txmcore-client-sdk.MPORG.1.0.2.jar</systemPath>
    </dependency>

</dependencies>

信息安全

签名算法

HTTP信息接口签名算法采用国家密码局于2010年12月发布的SM2算法。

其中的USERID：由平台分配（十六进制值）

SM2算法中默认的USERID为：31323334353637383132333435363738，本文档未采用默认值。

对于采用Java语言开发的前置服务，将提供相应的接入SDK。

Base64 编码

本系统采用的是URL Safe Base64算法

即先做传统base64编码，随后将+和/分别替换为- _两个字符，并且去除补位=。

另传统URL Safe Base64编码的转换表（Base64 Alphabet）为：

ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_

本系统将转换表进行了置乱（示例值，生产参数请联系平台）：

BaFGPul95Hhi8-opNefg20q3TA1VUvJOdxKWYZnr4bQLMjCIkwDXtE6zc7_RSmys

即：原索引0对应字符A，现在变成对应字符B，其它索引对应关系以此类推。

HTTP Header

在HTTP Header中存放以下参数：

参数	类型	必填	描述	示例值
openid	String	是	小程序商户ID	DVAAABa7u2UVzjt2j-YEml
mpid	String	是	小程序ID	MPAAABbdzoiyVwAVWB_Qm2
acctoken	String	是	数据签名	SI9ZmtnPUMD7JUyzpXQzWo2UQIamL68aOW2yyyZCEIaOXhiJLoWq4ChJzaeK-KxqzhxkBU8Ivs_R3whx9WxyFH
timestamp	String	是	时间戳（毫秒）	1563525207309
authtoken	String	否	用户令牌

签名数据组装规则

a) 将请求参数按字母顺序排列，然后进行拼接，此规则适应于含QueryParams的GET类请求以及参数类型为application/x-www-form-urlencoded 的POST类请求，如有以下参数(如果参数值为null、nil或空值的，则不拼接):

a=1;

bc="2131";
ba="3232";

拼接结果为

a=1&ba=3232&bc=2131

b) 对于POST类型请求会将请求数据放在body中，则也要加入进行签名（参与排序）。

entity=...

c) 拼接完参数后，需要将请求地址、时间戳也进行拼接。拼接在参数或entity后，不参与排序。

a=1&ba=3232&bc=2131&path=/users/login&timestamp=1563525207309

// post类：
entity=...&path=/users/login&timestamp=1563525207309

获取授权用户资料接口

API应用场景说明：

小程序商户根据授权token获取授权用户资料

请求地址：

请求方式	返回格式	请求地址
GET	Json	/users/getuserinfo

请求参数：[Query]

参数	类型	必填	名称	描述
accesstoken	String	是	授权token	用户授权的token

请求参数示例：

accesstoken=GuwrHb4p1wmST_iaAJaHzoNch0KKWCPpXn0SHAeRRQ12yAcDOrzQsdieMbWc2jB9dRgS_bJetDwl9Pd8awvEsXu5vEgJ8KGfMoCMeBLaDqR2K90E9d3MRPQzi4ofoZM5

响应参数：

参数	类型	名称
UserModel {}	Object	用户模型
unionid	String	用户唯一标识
appid	String	APPID
appname	String	APP名称
gender	Integer	性别 0女 1男 2未设置
nickname	String	昵称
avatar	String	头像key

响应参数示例：[Json]

200响应状态码

{
	"unionid": "UNAAABbyI7eOEre5x2Bxtg",
	"appid": "APAAABa7vrHaGjUJNIcZBi",
	"appname": "Playground",
	"gender": 1,
	"nickname": "小众",
	"avatar": "http://39.100.48.104:18080/avatar.png"
}

400响应状态码

{
    "code": 3000,
    "message": "未知错误"
}

获取授权用户手机号

API应用场景说明： since v0.28.2

小程序商户根据授权token获取授权用户手机号

请求地址：

请求方式	返回格式	请求地址
GET	Json	/users/getphoneno

请求参数：[Query]

参数	类型	必填	名称	描述
accesstoken	String	是	授权token	用户授权的token

请求参数示例：

accesstoken=GuwrHb4p1wmST_iaAJaHzoNch0KKWCPpXn0SHAeRRQ12yAcDOrzQsdieMbWc2jB9dRgS_bJetDwl9Pd8awvEsXu5vEgJ8KGfMoCMeBLaDqR2K90E9d3MRPQzi4ofoZM5

响应参数：

参数	类型	名称
PhoneNoModel {}	Object	用户手机号模型
unionid	String	用户唯一标识
appid	String	APPID
appname	String	APP名称
phoneno	String	手机号

响应参数示例：[Json]

200响应状态码

{
	"unionid": "UNAAABbyI7eOEre5x2Bxtg",
	"appid": "APAAABa7vrHaGjUJNIcZBi",
	"appname": "Playground",
	"phoneno": "13800138000"
}

400响应状态码

{
    "code": 3000,
    "message": "操作失败"
}

代金券赠送

API应用场景说明：

提供给第三方的代金券赠送接口

请求地址：

请求方式	返回格式	请求地址
POST	Json	/coupon/receive

请求参数：[FormData, application/x-www-form-urlencoded]

参数	类型	必填	名称	描述
requestorderid	String	是	请求订单号
senddesc	String	是	赠送描述	`100积分送乘车券`
activityid	Integer	是	方案id	`方案id`
unionid	String	是	用户唯一标识	`用户唯一标识`
quantity	Integer	是	送券数量

请求参数示例：

requestorderid=F20200606110908&senddesc=100&activityid=23&unionid=112313&quantity=2

响应参数：

参数	类型	名称	描述
ReceiveCouponModel[{}]	List	代金券模型
requestorderid	String	请求订单号
senddesc	String	赠送描述
activityid	Integer	方案ID
unionid	String	是	用户唯一标识
title	String	方案标题
couponvalue	Integer	代金券面值	单位：分
couponnumber	String	代金券标识码
isuse	Integer	是否已使用	0 否 1 是
beginat	String	有效期	开始时间
endat	String	有效期	截止时间

响应参数示例：[Json]

200响应状态码

[{
  "requestorderid": "APAAABa7vrHaGjUJNIcZBi",
  "senddesc": "100",
  "activityid": 23,
  "unionid":"123",
  "title":"积分兑换",
  "couponvalue": 140,
  "couponnumber": "20200606111426",
  "isuse":0,
  "beginat": "2020-03-26 16:23:54",
  "endat": "2020-06-26 16:23:54"
}]

400响应状态码

{
    "code": 4000,
    "message": "未知错误"
}

代金券对账

API应用场景说明：

对账、获取当日已使用的代金券列表

请求地址：

请求方式	返回格式	请求地址
GET	Json	/coupon/getbilllist

请求参数：[Query]

参数	类型	必填	描述
billdate	String	是	账单日期
limit	Integer	是	记录条数
offset	Integer	是	起始下标

请求参数示例：

billdate=2020-03-26&limit=100&offset=0

响应参数：

参数	类型	名称	描述
CouponModel[{}]	List	代金券模型
appid	String	APPID
appname	String	appname
unionid	String	用户唯一标识	`用户唯一标识`
requestorderid	String	请求订单号
senddesc	String	赠送描述
thirdorderno	String	消费订单号
orderamount	Integer	订单金额	单位：分
couponnumber	String	代金券标识码
couponvalue	Integer	代金券面值	单位：分
useat	String	使用时间

响应参数示例：[Json]

200响应状态码

[
  {
    "appid": "APAAABa7vrHaGjUJNIcZBi",
    "appname": "湘行一卡通",
    "unionid": "F1000002",
     "requestorderid": "F20200606112205",
     "senddesc": "100",
    "thirdorderno": "1000000001001",
    "orderamount": 200,
    "couponnumber": "3",
    "couponvalue": 149,
    "useat": "2020-03-26 16:23:54"
  }
]

400响应状态码

{
    "code": 4000,
    "message": "未知错误"
}

银商创建订单

API应用场景说明：

小程序商户银商创建订单。

本接口为商户的订单信息发向银商网络支付前置系统以获取支付要素。

如果需要实名认证（APP接口实名认证暂只支持支付宝），必传姓名name，证件类型certType，证件号certNo，强制校验位fixBuyer=T。注意：支付宝支持的证件类型包括：身份证IDENTITY_CARD、护照PASSPORT、军官证OFFICER_CARD、士兵证SOLDIER_CARD、户口本HOKOU".敏感信息如姓名、证件号和手机号信息需要 base64编码。

请求地址：

请求方式	返回格式	请求地址
POST	Json	/unionpay/order

请求参数：[FormData, application/x-www-form-urlencoded]

参数	类型	必填	名称	描述
unionid	String	是	用户唯一标识
appid	String	是	APPID
msgType	String	是	消息类型	微信（app跳转小程序支付）:wx.appPreOrder 微信（直连）wx.unifiedOrder 支付宝：trade.precreate 全民付：qmf.order 银联云闪付（走银联全渠道）：uac.appOrder ApplePay支付：applepay.order
requestTimestamp	String	是	报文请求时间	格式yyyy-MM-dd HH:mm:ss
tid	String	是	终端号
paytoken	String	是	支付token	收银台生成
merOrderId	String	是	商户订单号	商户自行生成，注意：长度不要超过32位
orderDesc	String	是	订单描述	不超过255个字节（微信支付：上送值不大于128个字节，超过128字节后的部分会被截掉）
totalAmount	Integer	是	支付总金额	单位分
originalAmount	Integer	否	订单原始金额	单位分，用于记录前端系统打折前的金额
attachedData	String	否	商户附加数据
expireTime	String	否	订单过期时间	订单过期时间，为空则使用系统默认过期时间（30分钟），格式yyyy-MM-dd HH:mm:ss
notifyUrl	String	否	支付结果通知地址
merchantUserId	String	否	商户用户号	全民付、applepay下单时必传
mobile	String	否	实名认证手机号	Base64编码
name	String	否	实名认证姓名	Base64编码
certType	String	否	实名认证证件类型	证件类型，支付宝支持身份证：IDENTITY_CARD、护照：PASSPORT、军官证：OFFICER_CARD、士兵证：SOLDIER_CARD、户口本：HOKOU
certNo	String	否	实名认证证件号	Base64编码
fixBuyer	String	否	是否需要实名认证	需要实名认证时置为 T
limitCreditCard	String	否	是否需要限制信用卡支付	取值：true或false，默认false
installmentNumber	Integer	否	花呗分期数	仅支持3、6、12 仅支持支付宝支付

请求参数示例：

appid=APAAABa7vrHaGjUJNIcZBi&merOrderId=O202005281141426870057655555&msgType=wx.appPreOrder&notifyUrl=https://zqmp.lmspay.com/pay-demo/order_notify&orderDesc=prod-1590637297577&originalAmount=1&paytoken=gkU02581UqyeV2dzA5oxs8u7md5nzpzTPW0ShBFclRnvL6AmtEGqEi0JE-APe2dMFwETwONgYWgV6bEFhvf6ZkWw-kO1a9KAPh7m81433q_mXU9No0n0CcBzBdmHUj0u2qd2_C8Rrk0ScEmt8zbaJM&requestTimestamp=2020-05-28 11:41:42&tid=TEST0001&totalAmount=1&unionid=UNAAABbtQJ_nJSOvHt_ewB

响应参数：

参数	类型	名称	描述
UnionPayOrderResponseModel{}	Object	银商创建订单返回模型
errCode	String	平台错误码	SUCCESS 表示请求成功
errMsg	String	平台错误信息	信息描述，中文，对应code的中文信息
msgId	String	消息ID	可协助后端快速排查问题
msgType	String	消息类型	微信（app跳转小程序支付）:wx.appPreOrder 微信（直连）wx.unifiedOrder 支付宝：trade.precreate 全民付：qmf.order 银联云闪付（走银联全渠道）：uac.appOrder ApplePay支付：applepay.order
responseTimestamp	String	报文响应时间	格式yyyy-MM-dd HH:mm:ss
tid	String	终端号
tradeno	String	小程序平台交易流水号
merOrderId	String	商户订单号
status	String	交易状态
totalAmount	Integer	支付总金额	单位分
targetOrderId	String	第三方支付订单号
targetSys	String	目标平台代码
targetStatus	String	目标平台的状态
jsPayRequest	String	JSAPI支付用的请求报文	带有签名信息
appPayRequest	String	APP支付用的请求报文	带有签名信息
prepayId	String	支付ID	用于APP支付和公众号支付
qrCode	String	支付二维码	内容为URL，由终端转换成二维码显示

响应参数示例：[Json]

200响应状态码

{
  "appPayRequest": "{\"package\":\"Sign=WXPay\",\"appid\":\"wx71d6944b3b508932\",\"sign\":\"3B8DC17037024C6C3FD36C5C21978111\",\"partnerid\":\"376543455\",\"prepayid\":\"672b73785f8e4bf4b68943268df088de\",\"noncestr\":\"tHWUPaAbvcasxolLeVUNVhgCvDhPAcjy\",\"timestamp\":\"20200528114142\"}",
  "errCode": "SUCCESS",
  "merOrderId": "O202005281141426870057655555",
  "msgId": "2020052811414275145158",
  "msgType": "wx.appPreOrder",
  "responseTimestamp": "2020-05-28 11:41:42",
  "targetSys": "WXPay",
  "tid": "TEST0001",
  "totalAmount": 1,
  "tradeno": "711212020052811414274796709"
}

400响应状态码

{
    "code": 3000,
    "message": "操作失败"
}

银商查询订单

API应用场景说明：

小程序商户银商查询订单。

钱包支付时，因通讯故障、服务器故障等原因，造成收银机最终没有收到支付结果通知，收银员不确定该笔支付后台处理结果，可以在收银机上发起“查询”交易，查询该笔交易订单在钱包后台的支付结果，并将支付结果返回给收银机。

请求地址：

请求方式	返回格式	请求地址
POST	Json	/unionpay/orderquery

请求参数：[FormData, application/x-www-form-urlencoded]

参数	类型	必填	名称	描述
msgType	String	是	消息类型	query
requestTimestamp	String	是	报文请求时间	格式yyyy-MM-dd HH:mm:ss
tid	String	是	终端号
tradeno	String	否	小程序平台交易流水号	三选一
merOrderId	String	否	商户订单号	三选一
targetOrderId	String	否	第三方支付订单号	三选一

请求参数示例：

merOrderId=O202005281205015446564381934&msgType=query&requestTimestamp=2020-05-28 12:08:04&tid=TEST0001

响应参数：

参数	类型	名称	描述
UnionPayOrderQueryResponseModel{}	Object	银商查询订单返回模型
errCode	String	平台错误码	SUCCESS 表示请求成功
errMsg	String	平台错误信息	信息描述，中文，对应code的中文信息
msgId	String	消息ID	可协助后端快速排查问题
msgType	String	消息类型
responseTimestamp	String	报文响应时间	格式yyyy-MM-dd HH:mm:ss
tid	String	终端号
tradeno	String	小程序平台交易流水号
merOrderId	String	商户订单号
targetOrderId	String	第三方支付订单号
status	String	交易状态
targetSys	String	目标平台代码
targetStatus	String	目标平台的状态
buyerId	String	买家ID
buyerUsername	String	买家用户名
subBuyerId	String	子买家ID	比如微信的subOpenId
bankCardNo	String	银行卡号	如果有的话
bankInfo	String	银行信息
totalAmount	Integer	支付总金额	单位分
buyerPayAmount	Integer	实付金额	单位分
invoiceAmount	Integer	开票金额	单位分，交易中可给用户开具发票的金额
couponAmount	Integer	网付计算的优惠金额	单位分
payTime	String	支付时间	格式yyyy-MM-dd HH:mm:ss
settleDate	String	结算日期	格式yyyy-MM-dd
billFunds	String	资金渠道	示例：支付宝余额:33I优惠券:55
billFundsDesc	String	资金渠道描述

响应参数示例：[Json]

200响应状态码

{
  "buyerUsername": "654***@qq.com",
  "msgType": "trade.query",
  "tradeno": "711212020052812050162647594",
  "payTime": "2020-05-28 12:05:16",
  "errMsg": "查询成功",
  "msgId": "2020052812102770274183",
  "invoiceAmount": 1,
  "settleDate": "2020-05-28",
  "billFunds": "支付宝余额:1",
  "buyerId": "2088802252480865",
  "tid": "TEST0001",
  "couponAmount": 0,
  "targetOrderId": "2020052822001480861408684890",
  "billFundsDesc": "支付宝余额支付0.01元。",
  "targetStatus": "SUCCESS",
  "merOrderId": "O202005281205015446564381934",
  "targetSys": "Alipay 2.0",
  "totalAmount": 1,
  "responseTimestamp": "2020-05-28 12:10:27",
  "errCode": "SUCCESS",
  "buyerPayAmount": 1,
  "status": "TRADE_SUCCESS"
}

400响应状态码

{
    "code": 3000,
    "message": "操作失败"
}

银商退款请求

API应用场景说明：

小程序商户银商退款请求。

当成功交易之后一段时间内，由于买家或商户的原因需要退款时，商户可以通过本接口将支付款退还给买家，退款请求验证成功之后，银商将通知支付渠道方按照退款规则把支付款按原路退回到买家帐号上。

请求地址：

请求方式	返回格式	请求地址
POST	Json	/unionpay/refund

请求参数：[FormData, application/x-www-form-urlencoded]

参数	类型	必填	名称	描述
msgType	String	是	消息类型	refund
requestTimestamp	String	是	报文请求时间	格式yyyy-MM-dd HH:mm:ss
tid	String	是	终端号
merOrderId	String	是	商户订单号
refundOrderId	String	是	商户退款订单号
refundAmount	Integer	是	退款金额	单位分
refundDesc	String	否	退款说明

请求参数示例：

merOrderId=O202005281141426870057655555&msgType=refund&refundAmount=1&refundDesc=test refund&refundOrderId=RO202005281141426870057655555&requestTimestamp=2020-05-28 11:55:38&tid=TEST0001

响应参数：

参数	类型	名称	描述
UnionPayRefundResponseModel{}	Object	银商退款请求返回模型
errCode	String	平台错误码	SUCCESS 表示请求成功
errMsg	String	平台错误信息	信息描述，中文，对应code的中文信息
msgId	String	消息ID	可协助后端快速排查问题
msgType	String	消息类型
responseTimestamp	String	报文响应时间	格式yyyy-MM-dd HH:mm:ss
tid	String	终端号
tradeno	String	小程序平台交易流水号
merOrderId	String	商户订单号
targetOrderId	String	第三方支付订单号
refundno	String	小程序平台退款流水号
refundOrderId	String	商户退款订单号
refundTargetOrderId	String	第三方退款订单号
refundAmount	Integer	退款金额	单位分
refundInvoiceAmount	Integer	实付部分退款金额	单位分
targetSys	String	目标平台代码
targetStatus	String	目标平台的状态
refundStatus	String	退款状态
refundFunds	String	退款资金渠道
refundFundsDesc	String	退款资金渠道描述

响应参数示例：[Json]

200响应状态码

{
  "errCode": "SUCCESS",
  "merOrderId": "O202005281141426870057655555",
  "msgId": "2020052811553819190134",
  "msgType": "wx.refund",
  "refundAmount": 1,
  "refundFunds": "现金:1",
  "refundFundsDesc": "现金退款0.01元。",
  "refundInvoiceAmount": 1,
  "refundOrderId": "RO202005281141426870057655555",
  "refundStatus": "SUCCESS",
  "refundTargetOrderId": "50100004232020052800709285231",
  "refundno": "711222020052811553818930626",
  "responseTimestamp": "2020-05-28 11:55:39",
  "targetStatus": "SUCCESS|SUCCESS",
  "targetSys": "WXPay",
  "tid": "TEST0001",
  "tradeno": "711212020052811414274796709"
}

400响应状态码

{
    "code": 3000,
    "message": "操作失败"
}

银商退款查询

API应用场景说明：

小程序商户银商退款查询。

钱包支付时，因通讯故障、服务器故障等原因，造成收银机最终没有收到退货结果通知，收银员不确定该笔退货后台处理结果，查询该笔退货交易订单在钱包后台的支付结果，并将退货结果返回给收银机。

请求地址：

请求方式	返回格式	请求地址
POST	Json	/unionpay/refundquery

请求参数：[FormData, application/x-www-form-urlencoded]

参数	类型	必填	名称	描述
msgType	String	是	消息类型	refundQuery
requestTimestamp	String	是	报文请求时间	格式yyyy-MM-dd HH:mm:ss
tid	String	是	终端号
refundno	String	否	小程序平台退款流水号	二选一
refundOrderId	String	否	商户退款订单号	二选一

请求参数示例：

msgType=refundQuery&refundOrderId=RO202005281141426870057655555&requestTimestamp=2020-05-28 11:55:39&tid=TEST0001

响应参数：

参数	类型	名称	描述
UnionPayRefundQueryResponseModel{}	Object	银商退款查询返回模型
errCode	String	平台错误码	SUCCESS 表示请求成功
errMsg	String	平台错误信息	信息描述，中文，对应code的中文信息
msgId	String	消息ID	可协助后端快速排查问题
msgType	String	消息类型
responseTimestamp	String	报文响应时间	格式yyyy-MM-dd HH:mm:ss
tid	String	终端号
tradeno	String	小程序平台交易流水号
merOrderId	String	商户订单号
targetOrderId	String	第三方支付订单号
refundno	String	小程序平台退款流水号
refundOrderId	String	商户退款订单号
refundTargetOrderId	String	第三方退款订单号
refundAmount	Integer	退款金额	单位分
refundInvoiceAmount	Integer	实付部分退款金额	单位分
targetSys	String	目标平台代码
targetStatus	String	目标平台的状态
bankCardNo	String	银行卡号	如果有的话
bankInfo	String	银行信息
refundStatus	String	退款状态
refundFunds	String	退款资金渠道
refundFundsDesc	String	退款资金渠道描述
refundPayTime	String	退款时间	格式yyyy-MM-dd HH:mm:ss
settleDate	String	结算日期	格式yyyy-MM-dd

响应参数示例：[Json]

200响应状态码

{
  "bankInfo": "农业银行(借记卡)",
  "errCode": "SUCCESS",
  "errMsg": "查询成功",
  "merOrderId": "O202005281141426870057655555",
  "msgId": "2020052811553936308811",
  "msgType": "wx.refundQuery",
  "refundAmount": 1,
  "refundFunds": "现金:1",
  "refundFundsDesc": "现金退款0.01元。",
  "refundInvoiceAmount": 1,
  "refundOrderId": "RO202005281141426870057655555",
  "refundPayTime": "2020-05-28 11:55:38",
  "refundStatus": "SUCCESS",
  "refundTargetOrderId": "50100004232020052800709285231",
  "refundno": "711222020052811553818930626",
  "responseTimestamp": "2020-05-28 11:55:39",
  "settleDate": "2020-05-28",
  "targetStatus": "SUCCESS",
  "targetSys": "WXPay",
  "tid": "TEST0001",
  "tradeno": "711212020052811414274796709"
}

400响应状态码

{
    "code": 3000,
    "message": "操作失败"
}

银商关闭订单

API应用场景说明：

小程序商户银商关闭订单

请求地址：

请求方式	返回格式	请求地址
POST	Json	/unionpay/close

请求参数：[FormData, application/x-www-form-urlencoded]

参数	类型	必填	名称	描述
msgType	String	是	消息类型	close
requestTimestamp	String	是	报文请求时间	格式yyyy-MM-dd HH:mm:ss
tid	String	是	终端号
tradeno	String	否	小程序平台交易流水号	二选一`对应银商商户订单号`
merOrderId	String	否	商户订单号	二选一

请求参数示例：

merOrderId=O202005281148597766999168021&msgType=close&requestTimestamp=2020-05-28 12:11:27&tid=TEST0001

响应参数：

参数	类型	名称	描述
UnionPayCloseResponseModel{}	Object	银商关闭订单返回模型
errCode	String	平台错误码	SUCCESS 表示请求成功
errMsg	String	平台错误信息	信息描述，中文，对应code的中文信息
msgId	String	消息ID	可协助后端快速排查问题
msgType	String	消息类型
responseTimestamp	String	报文响应时间	格式yyyy-MM-dd HH:mm:ss
tid	String	终端号
tradeno	String	小程序平台交易流水号
merOrderId	String	商户订单号
status	String	交易状态
targetSys	String	目标平台代码
targetStatus	String	目标平台的状态
totalAmount	Integer	支付总金额	单位分
settleDate	String	结算日期	格式yyyy-MM-dd

响应参数示例：[Json]

200响应状态码

{
  "msgType": "trade.close",
  "tradeno": "711212020052811485982517889",
  "msgId": "2020052812113034409900",
  "settleDate": "2020-05-28",
  "tid": "TEST0001",
  "totalAmount": 1,
  "responseTimestamp": "2020-05-28 12:11:30",
  "errCode": "SUCCESS",
  "targetStatus": "10000",
  "merOrderId": "O202005281148597766999168021",
  "status": "TRADE_CLOSED",
  "targetSys": "Alipay 2.0"
}

400响应状态码

{
    "code": 3000,
    "message": "操作失败"
}

银商支付结果异步通知

应用场景说明：

小程序商户银商支付结果异步通知，付款成功、退款等都会触发异步通知。

支付完成后，渠道方会通知网付前置账单系统，账单系统收到通知后会组织结果信息发送通知到商户的通知地址。商户的通知地址可以在商户信息中配置，也可以在上送详单信息时上送，若都多处都配置了通知地址，那么账单系统会把结果通知到所有的地址上。

注意：商户收到通知后，需要对通知做出响应：成功收到时响应”SUCCESS”；失败时响应”FAILED”。

针对重复收到通知的问题处理：

如果网付没有收到商户响应的SUCCESS字串，或者商户应答的报文中不包含SUCCESS字串，或者网络异常，系统会在24小时内尝试多次通知。商户收到重复通知时可以执行以下1或2进行处理:

1.商户主动调网付查询接口，以查询结果为准。

2.通知报文里面有商户订单号，商户可根据订单号和订单状态判断是否是重复通知，并忽略已经处理了的订单的重复通知。

参数	类型	名称	描述
openid	String	小程序商户ID
mpid	String	小程序ID
attachedData	String	商户附加数据
bankCardNo	String	银行卡号
bankInfo	String	银行信息
billFunds	String	资金渠道
billFundsDesc	String	资金渠道说明
buyerId	String	买家ID
buyerUsername	String	买家用户名
subBuyerId	String	子买家ID
tradeno	String	小程序平台交易流水号
merOrderId	String	商户订单号
orderDesc	String	订单描述
status	String	订单状态
buyerPayAmount	Integer	实付金额	单位分
totalAmount	Integer	支付总金额	单位分
invoiceAmount	Integer	开票金额	单位分
refundno	String	小程序平台退款流水号
refundOrderId	String	商户退款订单
refundAmount	Integer	退款金额	单位分
refundDesc	String	退款说明
targetOrderId	String	第三方支付订单号
refundTargetOrderId	String	第三方退款订单号
targetSys	String	目标平台代码
createTime	String	订单创建时间	格式yyyy-MM-dd HH:mm:ss
payTime	String	订单支付时间	格式yyyy-MM-dd HH:mm:ss
closeTime	String	订单关闭时间	格式yyyy-MM-dd HH:mm:ss
refundPayTime	String	订单退款时间	格式yyyy-MM-dd HH:mm:ss
settleDate	String	结算日期	格式yyyy-MM-dd
refundSettleDate	String	退款结算日期	格式yyyy-MM-dd
notifyId	String	通知ID
sign	String	签名

*支付回调结果示例*
```json
{
  "buyerUsername": "",
  "tradeno": "711212020052811414274796709",
  "payTime": "2020-05-28 11:47:48",
  "sign": "NhHvujI_Gim3NEeqR0kyumNK8sAvLvD9acuCCAFbeH_t8MxrBS8t7NRhiqmLgeHrS9QVPTwRZhL6pSWB5G8iDF",
  "invoiceAmount": "1",
  "settleDate": "2020-05-28",
  "billFunds": "现金:1",
  "buyerId": "otdJ_uGPmf3gymTdXT8SMJKjFNc8",
  "mpid": "MPAAABcicCKNKR7IVS4hyO",
  "refundTargetOrderId": "",
  "refundDesc": "",
  "attachedData": "",
  "closeTime": "",
  "targetOrderId": "4200000605202005286275291592",
  "billFundsDesc": "现金支付0.01元。",
  "subBuyerId": "o45PI5ZXYh4lS6gzQYALZkFn6WFs",
  "orderDesc": "prod-1590637297577",
  "merOrderId": "O202005281141426870057655555",
  "refundAmount": "",
  "targetSys": "WXPay",
  "bankInfo": "农业银行(借记卡)",
  "bankCardNo": "",
  "openid": "DVAAABbLK7Nw1l7_JG_MFO",
  "refundSettleDate": "",
  "refundOrderId": "",
  "totalAmount": "1",
  "refundno": "",
  "createTime": "2020-05-28 11:41:44",
  "buyerPayAmount": "1",
  "refundPayTime": "",
  "notifyId": "43d11f9f-aaad-47cd-a7ee-f82d5b7ccacd",
  "status": "TRADE_SUCCESS"
}

*退款回调结果示例*
```json
{
  "buyerUsername": "",
  "tradeno": "711212020052811414274796709",
  "payTime": "2020-05-28 11:47:48",
  "sign": "e-A7kZPte2gAcA4eEGwsN8QTvYIgM7Mp4Xm17_br7ZhJSwfbTbLfGSWbaovaF05pD3s5i6VhVC1vNJI00oXdRP",
  "invoiceAmount": "1",
  "settleDate": "2020-05-28",
  "billFunds": "现金:1",
  "buyerId": "otdJ_uGPmf3gymTdXT8SMJKjFNc8",
  "mpid": "MPAAABcicCKNKR7IVS4hyO",
  "refundTargetOrderId": "50100004232020052800709285231",
  "refundDesc": "test refund",
  "attachedData": "",
  "closeTime": "2020-05-28 11:55:39",
  "targetOrderId": "4200000605202005286275291592",
  "billFundsDesc": "现金支付0.01元。",
  "subBuyerId": "o45PI5ZXYh4lS6gzQYALZkFn6WFs",
  "orderDesc": "prod-1590637297577",
  "merOrderId": "O202005281141426870057655555",
  "refundAmount": "1",
  "targetSys": "WXPay",
  "bankInfo": "农业银行(借记卡)",
  "bankCardNo": "",
  "openid": "DVAAABbLK7Nw1l7_JG_MFO",
  "refundSettleDate": "2020-05-28",
  "refundOrderId": "RO202005281141426870057655555",
  "totalAmount": "1",
  "refundno": "711222020052811553818930626",
  "createTime": "2020-05-28 11:41:44",
  "buyerPayAmount": "1",
  "refundPayTime": "2020-05-28 11:55:38",
  "notifyId": "9e7b7e23-7dac-4ae7-be74-f5aee726b7cb",
  "status": "TRADE_REFUND"
}

银商错误码、状态码枚举值

应用场景说明：

小程序商户银商错误码、状态码枚举值。

errCode取值说明：

取值	描述	原因和应对措施	系统失败
SUCCESS	成功	无。
INTERNAL_ERROR	内部错误	系统错误，请联系技术支持。	是
BAD_REQUEST	请求报文有错	报文格式或字段值有误，请对照文档检查。	是
NO_SERVICE	没有能处理请求msgtype的服务	msgType错误，请检查文档，msgType是否拼写正确。	是
TIMEOUT	处理超时	处理超时，很可能是微信和支付宝的网络请求没应答，建议重试或者撤销交易。	是
NO_ORDER	找不到请求的原始订单	对应的mid+merOrderId不正确，无法找到原交易，请检查merOrderId是否跟原交易一致。	否
OPERATION_NOT_ALLOWED	当前不允许此操作	订单已经关闭，不能执行退货等操作。	否
TARGET_FAIL	支付宝方支付失败，如请求没有成功，或者请求成功，但是没有正确处理。	支付宝或者微信方业务失败，请根据返回信息确定具体原因。	否
DUP_ORDER	重复的订单请求	支付请求的merOrderId重复，请检查终端是否做过复位操作，导致流水号等重复。	是
NET_ERROR	跟支付包通讯出问题，包括请求发送异常，报文应答不是200，请求被取消，应答超时等。	通讯问题，联系运行检查网络情况。	是
NO_MERCHANT	找不到请求指定的商户	请求报文的mid在网付前置无法找到相关的配置，请确认终端的商户号是否正确在网付前置配置，是否经过转商户处理。	否
ORDER_PROCESSING	订单正在处理中，不允许并发操作。	当前订单的上一次操作没有完成，订单处于锁定状态，请等待一分钟后再试。	否
INACTIVE_MERCHANT	商户被置为inactive状态	交易商户在网付前置被冻结。	否
ABNORMAL_REQUEST_TIME	请求时间异常	请求终端或者平台的系统时间不正常，请检查系统时间。	是
TXN_DISCARDED	请求开始处理时间延迟过大，交易被丢弃。	系统负载过大，交易被丢弃，请联系运行。	是
BAD_SIGN	签名错误	报文签名错误，请联系技术指导签名算法。	是
INVALID_MSGSRC	商户来源错误	系统配置有问题，请联系技术。	是
INVALID_ORDER	订单信息异常	该订单支付时有异常，缺少关键数据，请先做一笔订单查询，补充关键数据后再次进行退货等操作。	是
NO_CROSS_DAY_TRADING	不允许跨日交易	可能某些渠道不支持跨日撤销，建议做退货。	否
DENIED_IP	不允许此IP交易	IP不在白名单中，请联系管理员确认。	否
INVLID_MERCHANT_CONFIG	错误的商户配置	商户配置参数有问题，请联系业务人员检查商户配置参数。	是
INVALID_RESPONSE	无效的应答报文	支付渠道方的应答报文有问题，比如验签失败、报文格式错误等。	是

refundStatus取值说明：

取值	描述	备注
UNKNOWN	不明确的交易状态	需要调退款查询接口确认退款结果
SUCCESS	退款成功
FAIL	退款失败
PROCESSING	退款处理中	需要调退款查询接口确认退款结果

status取值说明：

取值	描述	备注
NEW_ORDER	新订单
UNKNOWN	不明确的交易状态
TRADE_CLOSED	在指定时间段内未支付时关闭的交易；在交易完成全额退款成功时关闭的交易；支付失败的交易。	TRADE_CLOSED的交易不允许进行任何操作。
WAIT_BUYER_PAY	交易创建，等待买家付款。
TRADE_SUCCESS	支付成功
TRADE_REFUND	订单转入退货流程	退货可能是部分也可能是全部。

targetSys取值说明：

取值	描述	备注
Alipay 1.0	支付宝1.0协议	比较少用
Alipay 2.0	支付宝2.0协议	主流
WXPay	微信
YQB	壹钱包
QMF	全民付远程快捷
UnionPay	银联钱包
BaiDu	百度钱包
JD	京东钱包
SF	顺丰顺手付
COMM	交通银行
BestPay	翼支付
ACP	银联全渠道立码付
NetPayBills	银商网付平台账单模块
NetPayGtwy	银商网付平台网关模块
QmfWebPay	POS通插件WEB版
UAC	银联全渠道

400响应错误码

code:3000, message:"操作失败"
code:3001, message:"数据已存在"
code:3002, message:"参数验证失败"
code:3003, message:"数据不存在"
code:3004, message:"签名验证失败"
code:3005, message:"签名已过期"
code:3006, message:"没有该API访问权限"
code:3007, message:"无效授权token"
code:3008, message:"用户不存在"
code:3016, message:"银商支付，不允许退款操作"
code:3017, message:"银商支付，调用银商接口出现异常"
code:3018, message:"银商支付，入网角色异常"
code:3019, message:"银商支付，该支付订单号业务处理失败，请更换支付订单号"
code:3020, message:"银商支付，支付订单号不存在"
code:3021, message:"银商支付，该退款订单号业务处理失败，请更换退款订单号"
code:3022, message:"银商支付，该退款订单号重复，已经发起过退款申请"
code:3023, message:"银商支付，该支付订单号重复，已经发起过下单"
code:3024, message:"银商支付，该APP未配置微信appkey"
code:3025, message:"银商支付，该支付渠道暂未启用"
code:3026, message:"银商支付，收银台无效授权支付token"
code:3027, message:"银商支付，资金已划账，不允许退款操作"
code:3028, message:"银商支付，超过退款期限，不允许退款操作"
code:3029, message:"银商支付，退款订单号不存在"
code:-1, message:"系统错误"

# 集成 OpenApi SDK

# OpenApi SDK 初始化

# SDK Maven依赖

# 信息安全

# 签名算法

# Base64 编码

# HTTP Header

# 签名数据组装规则

# 获取授权用户资料接口

# 获取授权用户手机号

# 代金券赠送

# 代金券对账

# 银商创建订单

# 银商查询订单

# 银商退款请求

# 银商退款查询

# 银商关闭订单

# 银商支付结果异步通知

# 银商错误码、状态码枚举值

# 400响应错误码

集成 OpenApi SDK

OpenApi SDK 初始化

SDK Maven依赖

信息安全

签名算法

Base64 编码

HTTP Header

签名数据组装规则

获取授权用户资料接口

获取授权用户手机号

代金券赠送

代金券对账

银商创建订单

银商查询订单

银商退款请求

银商退款查询

银商关闭订单

银商支付结果异步通知

银商错误码、状态码枚举值

400响应错误码