服务端API调用协议（HPS）

• 服务端API通过HPS(HTTP GET或HTTP POST(contentType=application/x-www-form-urlencoded;charset=UTF-8))对外提供服务，需要授权访问；

• 如无特殊说明，本文档提供的业务接口都需要加上HPS接入标准请求参数,所以需申请HPS鉴权参数：商户（merchant_name）和对应的key；

• 申请hps商户前，您需要确定使用场景，并向业务相关财务了解收款公司；

• 收银台目前支持3种支付场景：PC Web、H5 Wap、Android APP,每个hps商户只能配置一个使用场景,所以多场景就要申请多个merchant_name;

• 申请hps商户时，需要提供您需要使用的接口URL、您服务器的出口IP、以及说明业务使用场景，发邮件给王智涛；

• 授权联系人：王智涛

• 接口负责人：赵振华

HPS接入标准请求参数

参数名称	参数说明	请求类型	是否必须	数据类型	schema
merchant_name	接入用户名,接入用户名从接入平台获取	query	true	string
signature_method	签名方法,目前固定传 MD5	query	true	string
signature	签名(详见 HPS请求签名算法)	query	true	string
timestamp	时间戳	query	true	string
xxx	业务参数（定义只描述业务参数，请求时都需要带上面4个参数）	query	false

HPS请求签名算法

1. 当前请求参数名的字母序进行升序排列（排序时区分大小写，signature和value为空的参数不参与签名）;
2. 将所有参数-值组合以 key=value 的形式拼成一个新字符串，不同参数值之间没有任何分隔符；
3. 最后加上对应的签名密钥 secretKey(此密钥在接入时由王智涛提供给游戏相关接入人员) 后进行MD5哈希运算。如MD5方法的输入的字符串为：key1=value1key2=value2secretKey；

支付下单

接口地址:https://hps4pay.sdo.com/hps4pay/unionPay/createOrderSimply

请求方式: HPS,建议使用POST

请求数据类型:application/x-www-form-urlencoded;charset=UTF-8

响应数据类型:*/*

接口描述:

支付下单

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
traceId	游戏订单号	query	true	string
orderUser	订单用户	query	true	string
inputOrderUser	输入订单用户	query	true	string
payUser	支付用户	query	true	string
appId	游戏id	query	true	integer(int32)
appName	游戏名称	query	true	string
orderSource	订单来源	query	true	string
productCode	商品代码(部分活动时有用,默认传1)	query	true	string
productName	商品名称	query	true	string
productAmount	商品数量	query	true	string
productUnit	商品单位	query	true	string
orderAmount	订单金额	query	true	string
deliverTarget	发货通知地址	query	true	string
clientIp	客户端ip	query	true	string
signature	HSP签名	query	true	string
merchant_name	HPS商户号	query	true	string
signature_method	HPS签名方式，固定MD5	query	true	string
timestamp	HPS时间	query	true	string
memo	备注	query	false	string
extend	订单扩展信息(发货时原文带回)	query	false	string
clientDeviceId	客户端标识	query	false	string
redirectUrl	跳转地址(PC/H5专用)	query	false	string
backUrl	返回地址(PC/H5专用)	query	false	string
areaId	区id	query	false	string
areaName	区名称	query	false	string
groupId	服id	query	false	string
groupName	服名称	query	false	string
orderRoleId	角色ID	query	false	string
orderRoleName	角色名	query	false	string
expiredTime	订单过期时间（东八区时间格式：yyyy-MM-dd HH:mm:ss）	query	false	string

响应参数:

参数名称	参数说明	类型	schema
return_code	响应代码 (0表示成功)	integer(int32)
return_message	响应信息	string(string)
data	响应数据(object)	OrderResultVo	OrderResultVo
resultCode	返回代码	integer(int32)
resultMsg	返回信息	string(string)
cashierUrl	跳转收银台的地址	string(string)

响应示例:

{
	"return_code": 0,
	"return_message": "success",
	"data": {
        "resultCode": 0,
	    "resultMsg": "",
		"cashierUrl": "https://unionpay.sdo.com/cashier/pay?orderId=UP010127026169231222111541000001&orderToken=0631be11058a43ffba79efe7cc6ee3a2"
	}
}

订单查询

接口地址:https://hps4pay.sdo.com/hps4pay/unionPay/queryOrderSimply

请求方式: HPS,建议使用POST

响应数据类型:*/*

接口描述:

订单查询

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
traceId	游戏订单号	query	true	string

响应参数:

参数名称	参数说明	类型	schema
return_code	响应代码	integer(int32)	integer(int32)
return_message	响应信息	string(string)	string(string)
data	响应数据(object)	Object	Object
orders	订单列表	OrderArray	Array
traceId	游戏订单号	string(string)
payOrderId	支付订单号	string(string)
payResult	支付结果(1=成功,其他=未支付)	integer(int32)
orderUser	订单用户, 商品平台下的用户标识, 如: 盛大数字账号等	string(string)
inputOrderUser	输入订单用户, 订单用户的显示账号信息	string(string)
productCode	商品代码(部分活动时有用,默认传1)	query	true
productName	商品名称	string(string)
productAmount	商品数量	string(string)
orderAmount	订单金额	string(string)
payValue	支付金额(用户实际支付的金额)	string(string)
memo	备注	string(string)
extend	订单扩展(发货时原文带回)	string(string)
appId	游戏id	string(string)
appName	游戏名称	string(string)
areaId	区id	string(string)
areaName	区名称	string(string)
clientIp	客户端ip	string(string)
payChannel	用户支付的渠道编号	int(int)

响应示例:

{
	"return_code": 0,
	"return_message": "success",
	"data": {
        "orders":[{
            "traceId": "f6184141-045e-4e98-9b42-caa6c9fa063a",
            "payOrderId": "UC011127026169231201000253000001",
            "payResult": 1,
            "orderUser": "1234",
            "inputOrderUser": "1234",
            "payUser": "1234",
            "productName": "商品名称",
            "productAmount": "1.0000",
            "orderAmount": "0.0100",
            "payValue": "0.0100",
            "memo": "备注",
            "extend": "{\"extendInfo\":\"扩展信息\"}",
            "appId": "791000008",
            "appName": "测试游戏",
            "areaId": "1",
            "areaName": "测试区",
            "clientIp": "242.217.139.140"
        }]
	}
}

发货通知接口（接入方实现,非HPS）

接口地址:接入方提供

请求方式:HTTP POST

请求数据类型:application/x-www-form-urlencoded;charset=UTF-8

响应数据类型:*/*

接口描述:

发货通知接口

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
traceId	游戏订单号	query	true	string
payOrderId	支付订单号	query	true	string
payResult	支付结果: 1=已支付，其他：未支付	query	true	integer(int32)
payTime	支付时间	query	true	string
orderUser	订单用户	query	true	string
inputOrderUser	输入订单用户	query	true	string
productCode	商品代码(部分活动时有用,默认传1)	query	true	string
productName	商品名称	query	true	string
productAmount	订单商品数量	query	true	string
productUnit	商品单位	query	true	string
orderAmount	订单金额	query	true	string
clientIp	客户端IP	query	false	string
extend	订单扩展	query	false	string
appId	游戏id	query	false	string
appName	游戏名称	query	false	string
areaId	区id	query	false	string
areaName	区名称	query	false	string
groupId	组id	query	false	string
groupName	组名称	query	false	string
orderRoleId	角色ID	query	false	string
orderRoleName	角色名	query	false	string
payChannel	支付渠道	query	false	string
paySubChannel	支付子渠道(对于IOS内购，1=沙盒)	query	false	string
payExtend	支付扩展字段	query	false	string

响应参数:

参数名称	参数说明	类型	schema
return_code	响应代码 (0表示成功)	integer(int32)
return_message	响应信息	string(string)
data	响应数据(object)	OrderResultVo	OrderResultVo
resultCode	返回代码(0表示成功，非零的情况下系统会重试5次)	integer(int32)
resultMsg	返回信息	string(string)

响应示例:

{
	"return_code": 0,
	"return_message": "success",
	"data": {
        "resultCode": 0,
	    "resultMsg": "success"
	}
}

退款请求

接口地址:https://hps4pay.sdo.com/hps4pay/unionPay/financialRefund

请求方式:HPS,建议使用POST

请求数据类型:application/x-www-form-urlencoded;charset=UTF-8

响应数据类型:*/*

接口描述:

发起订单退款请求，退款成功后会向notifyTarget发起退款成功通知（不成功不通知）

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
traceId	游戏订单号	query	true	string
payOrderId	支付订单号（来自发货通知）	query	true	string
refundAmount	退款金额。单位元	query	true	string
notifyTarget	退款通知地址(http,协议见下)	query	false	string
memo	退款备注	query	false	string

响应参数:

参数名称	参数说明	类型	schema
return_code	响应代码 (0表示成功)	integer(int32)
return_message	响应信息	string(string)
data	响应数据(object)	OrderResultVo	OrderResultVo
resultCode	返回代码(0表示成功，非零的情况下系统会重试5次)	integer(int32)
resultMsg	返回信息	string(string)
refundOrderId	收银台退款订单号	string(string)

响应示例:

{
	"return_code": 0,
	"return_message": "success",
	"data": {
        "resultCode": 0,
	    "resultMsg": "success",
        "refundOrderId": "F1010127026168240326153938000001",
	}
}

退款成功通知（接入方实现，非HPS）

接口地址:接入方提供

请求方式:HTTP POST

请求数据类型:application/x-www-form-urlencoded;charset=UTF-8

响应数据类型:*/*

接口描述:

退款请求成功退款后向商户发起的通知消息

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
traceId	游戏订单号	query	true	string
payOrderId	订单号	query	true	string
refundAmount	退款金额。单位元	query	true	string
memo	退款备注	query	false	string

响应参数:

参数名称	参数说明	类型	schema
return_code	响应代码 (0表示成功)	integer(int32)
return_message	响应信息	string(string)
data	响应数据(object)	OrderResultVo	OrderResultVo
resultCode	返回代码(0表示成功，非零的情况下系统会重试5次)	integer(int32)
resultMsg	返回信息	string(string)

响应示例:

{
	"return_code": 0,
	"return_message": "success",
	"data": {
        "resultCode": 0,
	    "resultMsg": "success"
	}
}

支付渠道编号(payChannel)定义：

支付渠道编号	支付方式名称	说明
3	支付宝PC
10003	支付宝PC	支付宝PC备用通道号
32	支付宝H5
10032	支付宝H5	支付宝H5备用通道号
31	支付宝APP
10031	支付宝APP	支付宝APP备用通道号
40	微信PC
10040	微信PC	微信PC备用通道号
4000	微信H5
42	微信APP
10042	微信APP	微信APP备用通道号