GHOME SDK 文档 - 支付中心

# 服务端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
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"
	}
}
1
2
3
4
5
6
7
8
9

# 订单查询

接口地址: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"
        }]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

接口地址:接入方提供

请求方式:HTTP POST

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

响应数据类型:*/*

接口描述:

发货通知接口

接口安全:

游戏服务器可对请求IP做限制：114.80.132.9,101.227.2.236

接入方需按照HPS请求签名算法加签请求参数，不需要传merchant_name，不需要找王智涛做授权，加签使用的KEY可在联调时直接与支付中心技术支持约定

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 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"
	}
}
1
2
3
4
5
6
7
8

# 退款请求

接口地址: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",
	}
}
1
2
3
4
5
6
7
8
9

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

接口地址:接入方提供

请求方式:HTTP POST

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

响应数据类型:*/*

接口描述:

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

接口安全:

游戏服务器可对请求IP做限制：114.80.132.9,101.227.2.236

接入方需按照HPS请求签名算法加签请求参数，不需要传merchant_name，不需要找王智涛做授权，加签使用的KEY可在联调时直接与支付中心技术支持约定

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 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"
	}
}
1
2
3
4
5
6
7
8

# 支付渠道编号(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备用通道号
Last Updated: 2024/9/27 01:10:25

← 系统概述 →