🚀API对接指南

为了确保交易数据的安全性和完整性，调用支付网关的所有API接口都需要使用HTTPS协议和 HMAC-SHA512签名。

协议规则

以下指定了访问支付网关时调用 API 的规则：

规则	描述
传输协议	必须使用HTTPS传输数据
提交模式	POST或GET，取决于API
数据格式（内容类型）	提交的数据和响应都是 application/json 格式
字符编码	使用 UTF-8 字符编码
签名算法	HMAC-SHA512
签名要求	请求和接收数据需要进行签名检查
逻辑判断	确定协议字段、服务字段和交易状态

请求头

属性	类型	是否必需	限制	描述
content-type	string	是	application/json	内容类型
HiicashPay-Timestamp	int64	是	只处理 1 秒内发送的请求，以确保机器时间与网络同步	Unix 时间戳，以毫秒为单位
HiicashPay-Nonce	string	是	必须是 32 位字符	一个 32 字节的随机字符串
HiicashPay-AppId	string	是	由支付网关生成的 AppID	新建应用时生成的app_id
HiicashPay-Signature	string	是	使用 SHA512 生成的签名，并为大写字符串	生成签名

签名算法

Java

body = objectMapper.writeValueAsBytes(req);
String payload = timestamp + "\n" + nonce + "\n" + body + "\n";

PHP

Python

注意：

• '\n'为LF，ASCII值为'0x0A'

• 参数名称区分大小写

• 当检查返回的数据或消息推送的签名时，需将HiicashPay-Signature参数排除在外。

• 当提交json时，请仔细检查引号，'跟"不一样。

对内容进行签名

Java

String signature = hex(hmac("sha512", payload, secretKey)).toUpperCase()

PHP

Python

支付接口

商户业务系统通过支付订单接口发起支付收款订单，支付网关会根据商户配置的支付通道路由支付通道完成支付下单。支付网关根据不同的支付方式返回对应的支付参数，业务系统使用支付参数发起收款。

创建订单

请求URL：/pay/order/create

请求方式：POST

请求类型：application/json

请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	mchNo	是	String(30)	8812345812345678	商户号
应用ID	appId	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户生成的订单号
支付金额	amount	是	int	100	支付金额,单位分
支付数据类型	payDataType	是	String	Cashier	支付参数类型 收银台方式-Cashier 网关方式-Gateway
货币代码	currency	是	String(3)	USD	三位货币代码,美元:USD
客户端IP	clientIp	否	String(32)	210.73.10.148	客户端IPV4地址
商品标题	subject	是	string(64)	电子产品	商品的标题
商品信息	body	否	String(256)	{[ "title" : "xxxxxx", "price": 100, "qt": 1]}	商品详细信息列表 title-标题 price-价格 qt-数量
异步通知地址	notifyUrl	是	String(128)	https://www.hiicash.com/notify	支付结果异步回调URL,如果不填则使用后台设置的异步通知地址
跳转通知地址	returnUrl	否	String(128)	https://www.hiicash.com/return	支付结果同步跳转通知URL
失效时间	expiredTime	否	int	3600	订单失效时间,单位秒,默认1小时.订单在(创建时间+失效时间)后失效

示例数据

{
  "amount": 8,
  "mchOrderNo": "8812345812345678001",
  "payDataType": "Gateway",
  "subject": "电子产品",
  "body": "{[\"title\":\"华为手机\",\"price\":\"500000\", \"qt\":\"1\"]}",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "clientIp": "192.166.1.132",
  "notifyUrl": "https://www.example.com",
  "currency": "USD",
  "returnUrl": "",
  "mchNo": "8812345812345678",
  "expiredTime": 3600
}

返回参数

字段名	变量名	必填	类型	示例值	描述
返回状态	code	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	msg	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误
返回数据	data	否	String(512)	{}	返回下单数据,json格式

Data数据格式

字段名	变量名	必填	类型	示例值	描述
支付订单号	payOrderId	是	String(30)	U12021022311124442600	返回支付系统订单号
商户订单号	mchOrderNo	是	String(30)	8812345812345678123	返回商户传入的订单号
订单状态	orderState	是	int	2	支付订单状态 0-订单生成 1-支付中 2-支付成功 3-支付失败 4-已撤销 5-已退款 6-订单关闭
支付数据类型	payDataType	是	String	Cashier	支付参数类型 收银台方式-Cashier 网关方式-Gateway
支付数据	payData	否	String	http://www.hiicash.com/pay.html	返回收银台地址
渠道错误码	errCode	否	String	ACQ.PAYMENT_AUTH_CODE_INVALID	上游渠道返回的错误码
渠道错误描述	errMsg	否	String	Business Failed 失败	上游渠道返回的错误信息描述

成功示例数据

{
  "code": 0,
  "data": {
    "mchOrderNo": "8812345812345678",
    "orderState": 3,
    "payOrderId": "202106181642329900002",
    "payDataType": "Cashier",
    "payData": "https://www.hiicash.com/pay?order_id=202106181642329900002"
  },
  "msg": "SUCCESS"
}

失败示例数据

{
  "code": 0,
  "data": {
    "errCode": "ACQ.PAYMENT_AUTH_CODE_INVALID",
    "errMsg": "Business Failed",
    "mchOrderNo": "8812345812345678",
    "orderState": 3,
    "payOrderId": "P202106181642329900002"
  },
  "msg": "SUCCESS"
}

接入演示

以 Python 为例

Body 请求体

{
    "mchNo": "736251",
    "appId": app_id,
    "mchOrderNo": "UUEPFQKSKBX3SEHU",
    # HiiCash 网关所有金额均以「分」为单位，如果你的系统计算金额为元，这里要乘以 100
    # 以下 10860 实际支付金额为 $108.60
    "amount": 10860,
    "payDataType": "Cashier",
    "currency": "USD",
    "subject": "Suning Gift Card 苏宁易购礼品卡 x 1",
    "notifyUrl": "https://hiishop.test/pay/hiicash/notify",
    "returnUrl": "https://hiishop.test/detail-order-sn/UUEPFQKSKBX3SEHU"
}

Headers 请求头

{
    "Content-Type": "application/json; charset=utf-8",
    "HiicashPay-Timestamp": timestamp,
    "HiicashPay-Nonce": nonce,
    "HiicashPay-AppId": app_id,
    "HiicashPay-Signature": signature
}

下面我们来一步一步接入

# 依赖库
import hashlib
import hmac
import json
import random
import string
import time
import requests

# 获取 Nonce 32位随机字符串
def generate_nonce(length):
    return "".join(random.choices(string.ascii_letters + string.digits, k=length))

# 计算签名
def generate_signature(timestamp, nonce, body_str, secret_key):
    payload = timestamp + "\n" + nonce + "\n" + body_str + "\n"
    hash_obj = hmac.new(secret_key.encode("utf-8"), msg=payload.encode("utf-8"), digestmod=hashlib.sha512)
    signature = hash_obj.digest()
    return signature.hex().upper()

# 获取网关地址
def gateway_url():
    url = 'https://hiicash.oss-ap-northeast-1.aliyuncs.com/gateway.txt'
    response = requests.get(url)
    if response.status_code == 200:
        content = response.text
        return content + 'pay/order/create'
    else:
        print('Failed to fetch content from URL')

# 主程序
def main():
        # 商户号，必填，在商户后台查看
        mch_no = "736251"
        
        # 应用ID，必填，在商户后台查看
        app_id = "01hccpzwwbjn7gqmcc466w729j"
        
        # 应用密钥，必填，在商户后台查看
        secret_key = "7oOSE6WeJRdOHgtoIujrBGgrBDYu428dKpkkVUzWSXxfoFhYXOrh3KoyyEyhoON8"
        
        # 网关地址
        url = gateway_url()
        
        body = {
                "mchNo": mch_no,
                "appId": app_id,
                "mchOrderNo": "UUEPFQKSKBX3SEHU",
                "amount": 10860,
                "payDataType": "Cashier",
                "currency": "USD",
                "subject": "Suning Gift Card 苏宁易购礼品卡 x 1",
                "notifyUrl": "https://shop.hii.cash/pay/hiicash/notify",
                "returnUrl": "https://shop.hii.cash/detail-order-sn/UUEPFQKSKBX3SEHU"
        }
        
        # timestamp = str(int(time.time() * 1000)) 这里先不着急传参请求接口，先把签名计算正确
        timestamp = "1712325091543"
        
        # nonce = generate_nonce(32) 这里先不着急传参请求接口，先把签名计算正确
        nonce = "6r5BBE54OE9JGHcVNYBDxOvyvbnng0i5"
        
        # 注意这里转换后的 JSON 字符串必须是双引号""，且不能有空格；
        # body_str 的值应为：
        # {"mchNo":"736251","appId":"01hccpzwwbjn7gqmcc466w729j","mchOrderNo":"UUEPFQKSKBX3SEHU","amount":10860,"payDataType":"Cashier","currency":"USD","subject":"Suning Gift Card 苏宁易购礼品卡 x 1","notifyUrl":"https://shop.hii.cash/pay/hiicash/notify","returnUrl":"https://shop.hii.cash/detail-order-sn/UUEPFQKSKBX3SEHU"}
        body_str = json.dumps(body, ensure_ascii=False, separators=(",", ":"))
        
        # 生成签名
        signature = generate_signature(timestamp, nonce, body_str, secret_key)
        
        # 这里打印的签名应该是：
        # 20628DE35D2B36F9530F91B1F58E8084E3B032B5F9A124EC5E20B3C1F8208A7E281366E66AA37F665744013923F2B4A3FE330F288B001BA4AB5EDD39F95A8CF2
        print(signature)

按照上面的步骤，最终生成的签名应该是：

20628DE35D2B36F9530F91B1F58E8084E3B032B5F9A124EC5E20B3C1F8208A7E281366E66AA37F665744013923F2B4A3FE330F288B001BA4AB5EDD39F95A8CF2

如果你的签名不一致，请不要着急先传入参数，先按照上方全部付复制，不要修改任何变量，直到签名计算正确为止。

下面来发送请求

将 main() 方法方法中的

mch_no
app_id
secret_key

三个变量的值换为你商户后台的应用网关信息

删除以下代码

nonce = "6r5BBE54OE9JGHcVNYBDxOvyvbnng0i5"
timestamp = "1712325091543"

打开注释

nonce = generate_nonce(32)
timestamp = str(int(time.time() * 1000))

Body 信息改为你自己的

body = {
    # 6 位商户号
    "mchNo": mch_no,
    # 商户的应用ID
    "appId": app_id,
    # 商户订单号
    "mchOrderNo": "",
    # HiiCash 网关所有金额均以「分」为单位，如果你的系统计算金额为元，这里要乘以 100
    # 以下 10860 实际支付金额为 $108.60
    "amount": 10860,
    # 忽略
    "payDataType": "Cashier",
    # 忽略，不接受其他货币，如果你的系统是其他货币，请自行计算汇率差
    "currency": "USD",
    # 支付商品名称
    "subject": "Suning Gift Card 苏宁易购礼品卡 x 1",
    # 回调地址
    "notifyUrl": "https://shop.hii.cash/pay/hiicash/notify",
    # 支付成功跳转地址
    "returnUrl": "https://shop.hii.cash/detail-order-sn/UUEPFQKSKBX3SEHU"
}

# 依赖库
import hashlib
import hmac
import json
import random
import string
import time
import requests


# 获取 Nonce 32位随机字符串
def generate_nonce(length):
    return "".join(random.choices(string.ascii_letters + string.digits, k=length))


# 计算签名
def generate_signature(timestamp, nonce, body_str, secret_key):
    payload = timestamp + "\n" + nonce + "\n" + body_str + "\n"
    hash_obj = hmac.new(secret_key.encode("utf-8"), msg=payload.encode("utf-8"), digestmod=hashlib.sha512)
    signature = hash_obj.digest()
    return signature.hex().upper()


# 获取网关地址
def gateway_url():
    url = 'https://hiicash.oss-ap-northeast-1.aliyuncs.com/gateway.txt'
    response = requests.get(url)
    if response.status_code == 200:
        content = response.text
        return content + 'pay/order/create'
    else:
        print('Failed to fetch content from URL')


# 主程序
def main():
    # 商户号，必填，在商户后台查看
    mch_no = "736251"

    # 应用ID，必填，在商户后台查看
    app_id = "01hccpzwwbjn7gqmcc466w729j"

    # 应用密钥，必填，在商户后台查看
    secret_key = "7oOSE6WeJRdOHgtoIujrBGgrBDYu428dKpkkVUzWSXxfoFhYXOrh3KoyyEyhoON8"

    # 网关地址
    url = gateway_url()

    body = {
        "mchNo": mch_no,
        "appId": app_id,
        "mchOrderNo": "UUEPFQKSKBX3SEHU",
        "amount": 10860,
        "payDataType": "Cashier",
        "currency": "USD",
        "subject": "Suning Gift Card 苏宁易购礼品卡 x 1",
        "notifyUrl": "https://shop.hii.cash/pay/hiicash/notify",
        "returnUrl": "https://shop.hii.cash/detail-order-sn/UUEPFQKSKBX3SEHU"
    }

    timestamp = str(int(time.time() * 1000))

    nonce = generate_nonce(32)

    # 注意这里转换后的 JSON 字符串必须是双引号""，且不能有空格；
    # body_str 的值应为：
    # {"mchNo":"736251","appId":"01hccpzwwbjn7gqmcc466w729j","mchOrderNo":"UUEPFQKSKBX3SEHU","amount":10860,"payDataType":"Cashier","currency":"USD","subject":"Suning Gift Card 苏宁易购礼品卡 x 1","notifyUrl":"https://shop.hii.cash/pay/hiicash/notify","returnUrl":"https://shop.hii.cash/detail-order-sn/UUEPFQKSKBX3SEHU"}
    body_str = json.dumps(body, ensure_ascii=False, separators=(",", ":"))

    # 生成签名
    signature = generate_signature(timestamp, nonce, body_str, secret_key)

    headers = {
        "Content-Type": "application/json; charset=utf-8",
        "HiicashPay-Timestamp": timestamp,
        "HiicashPay-Nonce": nonce,
        "HiicashPay-AppId": app_id,
        "HiicashPay-Signature": signature
    }

    response = requests.post(url, data=body_str.encode('utf-8'), headers=headers)

    # 打印 response
    print(response.text)

    if response.status_code == 200:
        print("接口请求成功")
    else:
        print("接口请求失败")

if __name__ == "__main__":
    main()

如果一切顺利，你得到的值为：

{
    "code": 0,
    "message": "Ok",
    "data": {
        "errCode": "",
        "errMsg": "",
        "mchOrderNo": "UUEPFQKSKBX3SEHU",
        "orderState": "FAILED",
        "payOrderId": "631548235529060872",
        "payDataType": "Cashier",
        "payData": "https://pay.hiicash.app/payment?order_id=631536792545001992&redirect_to=https://shop.hii.cash/detail-order-sn/UUEPFQKSKBX3SEHU",
        "expireTime": 1712327393178
    }
}

返回值中的 data 的 payDataType 就是收银台支付链接，直接跳转即可。

查询订单

商户通过该接口查询订单，支付网关会返回订单最新的数据

请求URL：/pay/order/query

请求方式：POST

请求类型：application/json

请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	mchNo	是	String(30)	8812345812345678	商户号
应用ID	appId	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
支付订单号	payOrderId	是	String(30)	U12021022311124442600	返回支付系统订单号,与mchOrderNo二者传一即可
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户生成的订单号，与payOrderId二者传一即可

示例数据

{
  "payOrderId": "202306181104177050002",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "mchNo": "8812345812345678",
}

返回参数

字段名	变量名	必填	类型	示例值	描述
返回状态	code	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	msg	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误
返回数据	data	否	String(512)	{}	返回下单数据,json格式

Data数据格式

字段名	变量名	必填	类型	示例值	描述
支付订单号	payOrderId	是	String(30)	U12021022311124442600	返回支付系统订单号
商户号	mchNo	是	String(30)	8812345812345678	商户号
商户订单号	mchOrderNo	是	String(30)	8812345812345678123	返回商户传入的订单号
应用ID	appId	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
支付方式	wayCode	是	String(30)	VOUCHER	支付方式,如Voucher：VOUCHER，用户余额:BALANCE
支付接口	ifCode	是	String(30)	WEB	支付接口，WEB、APP、MINIPRAM……
支付金额	amount	是	int	100	支付金额,单位分
货币代码	currency	是	String(3)	cny	三位货币代码,美元:USD 人民币:CNY
订单状态	orderState	是	int	2	支付订单状态 0-订单生成 1-支付中 2-支付成功 3-支付失败 4-已撤销 5-已退款 6-订单关闭
客户端IP	clientIp	否	String(32)	210.73.10.148	客户端IPV4地址
商品标题	subject	是	string(64)	电子产品	商品的标题
商品信息	body	否	String(256)	{[ "title" : "xxxxxx", "price": 100, "qt": 1]}	商品详细信息列表 title-标题 price-价格 qt-数量
渠道订单号	channelOrderNo	否	String	20160427210604000490	对应渠道的订单号
渠道用户	channelUser	否	String	882010423410394	渠道用户号 voucher卡号或者user_id
扩展参数	extParam	否	String(512)	134586944573118714	商户扩展参数,回调时会原样返回
渠道错误码	errCode	否	String	ACQ.PAYMENT_AUTH_CODE_INVALID	上游渠道返回的错误码
渠道错误描述	errMsg	否	String	Business Failed 失败	上游渠道返回的错误信息描述
创建时间	createdAt	是	long	1622016572190	订单创建时间,13位时间戳
成功时间	successTime	否	long	1622016572190	订单支付成功时间,13位时间戳

示例数据

{
  "code": 0,
  "data": {
    "amount": 58,
    "appId": "60cc09bce4b0f1c0b83761c9",
    "subject": "电子产品",
    "body": "{[\"title\":\"华为手机\",\"price\":\"500000\", \"qt\":\"1\"]}",
    "channelOrderNo": "2021061822001423031419593035",
    "clientIp": "192.166.1.132",
    "createdAt": 1623985457705,
    "currency": "USD",
    "extParam": "",
    "ifCode": "WEB",
    "mchNo": "881623984572",
    "mchOrderNo": "20231623985457320",
    "payOrderId": "202306181104177050002",
    "state": 2,
    "successTime": 1623985459000,
    "wayCode": "VOUCHER",
    "channelUser": "882010423410394"
  },
  "msg": "SUCCESS",
}

关闭订单

商户通过该接口关闭订单，支付网关会对订单完成关闭处理。

请求URL：/pay/order/close

请求方式：POST

请求类型：application/json

请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	mchNo	是	String(30)	8812345812345678	商户号
应用ID	appId	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
支付订单号	payOrderId	是	String(30)	U12021022311124442600	返回支付系统订单号,与mchOrderNo二者传一即可
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户生成的订单号，与payOrderId二者传一即可

示例数据

{
  "payOrderId": "202306181104177050002",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "mchNo": "8812345812345678",
  "version": "1.0"
}

返回参数

字段名	变量名	必填	类型	示例值
返回状态	code	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	msg	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误
返回数据	data	否	String(512)	{}	返回下单数据,json格式

Data数据格式

字段名	变量名	必填	类型	示例值	描述
渠道错误码	errCode	否	String	ACQ.PAYMENT_AUTH_CODE_INVALID	上游渠道返回的错误码
渠道错误描述	errMsg	否	String	Business Failed 失败	上游渠道返回的错误信息描述

示例数据

{
  "code": 0,
  "data": {
    "errCode": "",
    "errMsg": ""
  },
  "msg": "SUCCESS"
}

支付通知

当订单支付成功时，支付网关会向商户系统发起回调通知。如果商户系统没有正确返回，支付网关会延迟再次通知。

请求URL：链接是通过创建订单接口提交的参数notifyUrl设置，或者商家在后台设置的回调URL

请求方式：POST

请求类型：application/json

请求头

属性	类型	描述
content-type	string	application/json
HiicashPay-Timestamp	int64	网关返回Unix时间戳
HiicashPay-Nonce	string	32位字符
HiicashPay-Signature	string	网关返回签名

示例数据

{
    "hiicashpay-nonce": [
        "4ecc7df017b83042a6111cc29e1e1d60"
    ],
    "hiicashpay-signature": [
        "153441317DD35AE8B9CA5CED2577EE4BD5B13FC6D6DBB8D3233715FB08D0899318F397C95D8FE11C35A5B823A21F92B5FB82EB35C49A44AB1389F9EFD75DCED4"
    ],
    "hiicashpay-timestamp": [
        "1712426009752"
    ],
    "content-type": [
        "application/json;charset=utf-8"
    ],
}

请求参数

支付订单号	payOrderId	是	String(30)	U12021022311124442600	返回支付系统订单号
商户号	mchNo	是	String(30)	8812345812345678	商户号
商户订单号	mchOrderNo	是	String(30)	8812345812345678123	返回商户传入的订单号
应用ID	appId	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
支付方式	wayCode	是	String(30)	VOUCHER	支付方式,如Voucher：VOUCHER，用户余额:BALANCE
支付接口	ifCode	是	String(30)	WEB	支付接口，WEB、APP、MINIPRAM……
支付金额	amount	是	int	100	支付金额,单位分
货币代码	currency	是	String(3)	cny	三位货币代码,美元:USD 人民币:CNY
订单状态	orderState	是	int	2	支付订单状态 0-订单生成 1-支付中 2-支付成功 3-支付失败 4-已撤销 5-已退款 6-订单关闭
客户端IP	clientIp	否	String(32)	210.73.10.148	客户端IPV4地址
商品标题	subject	是	string(64)	电子产品	商品的标题
商品信息	body	是	String(256)	{[ "title" : "xxxxxx", "price": 100, "qt": 1]}	商品详细信息列表 title-标题 price-价格 qt-数量
渠道订单号	channelOrderNo	否	String	20160427210604000490	对应渠道的订单号
渠道用户	channelUser	否	String	882010423410394	渠道用户号 voucher卡号或者user_id
扩展参数	extParam	否	String(512)	134586944573118714	商户扩展参数,回调时会原样返回
渠道错误码	errCode	否	String	ACQ.PAYMENT_AUTH_CODE_INVALID	上游渠道返回的错误码
渠道错误描述	errMsg	否	String	Business Failed 失败	上游渠道返回的错误信息描述
创建时间	createdAt	是	long	1622016572190	订单创建时间,13位时间戳
成功时间	successTime	否	long	1622016572190	订单支付成功时间,13位时间戳

示例数据

 {
    "amount": 58,
    "appId": "60cc09bce4b0f1c0b83761c9",
    "subject": "电子产品",
    "body": "{[\"title\":\"华为手机\",\"price\":\"500000\", \"qt\":\"1\"]}",
    "channelOrderNo": "2021061822001423031419593035",
    "clientIp": "192.166.1.132",
    "createdAt": 1623985457705,
    "currency": "USD",
    "extParam": "",
    "ifCode": "WEB",
    "mchNo": "881623984572",
    "mchOrderNo": "20231623985457320",
    "payOrderId": "202306181104177050002",
    "state": 2,
    "successTime": 1623985459000,
    "wayCode": "VOUCHER",
    "channelUser": "882010423410394"
  }

返回结果

业务系统处理后同步返回给支付中心，返回参数的returnCode为 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。 （通知频率为0/30/60/90/120/150,单位：秒）

字段名	变量名	必填	类型	示例值	描述
返回状态	returnCode	是	string(30)	"success"	"success"-处理成功，其他-处理有误
返回信息	returnMsg	否	String(128)	""	具体错误原因

示例数据

{
    "returnCode": "success",
    "returnMsg": ""
}

签名校验

HiiCash 网关默认返回信息已经是按照键名首字母升序排序，如果你是手动获取的参数，需要将 post 参数按照键名升序排序

通知回调签名校验与创建订单相同，只不过参数变成网关发送的请求数据，签名后再与网关签名进行比对，如果一致则代表订单完成，下面以 Python 为例：

# 依赖库
import hashlib
import hmac
import json

# 计算签名
def generate_signature(timestamp, nonce, body_str, secret_key):
    payload = timestamp + "\n" + nonce + "\n" + body_str + "\n"
    hash_obj = hmac.new(secret_key.encode("utf-8"), msg=payload.encode("utf-8"), digestmod=hashlib.sha512)
    signature = hash_obj.digest()
    return signature.hex().upper()


# 主程序
def main():
    # 应用密钥，必填，在商户后台查看
    secret_key = "7oOSE6WeJRdOHgtoIujrBGgrBDYu428dKpkkVUzWSXxfoFhYXOrh3KoyyEyhoON8"

    # 自行获取 Headers 中的以下参数
    headers = {
        "Content-Type": "application/json; charset=utf-8",
        "HiicashPay-Timestamp": "1712426009752",
        "HiicashPay-Nonce": "4ecc7df017b83042a6111cc29e1e1d60",
        "HiicashPay-Signature": "153441317DD35AE8B9CA5CED2577EE4BD5B13FC6D6DBB8D3233715FB08D0899318F397C95D8FE11C35A5B823A21F92B5FB82EB35C49A44AB1389F9EFD75DCED4"
    }

    # 自行获取接口中的以下参数
    body = {
        "amount": 716,
        "appId": "01htam5q8dc2sdjnjf81akx7dd",
        "goodsDetail": "{}",
        "channelOrderNo": "631708196754194436",
        "clientIp": "157.254.20.97",
        "createdAt": 1712425958059,
        "currency": "USD",
        "extParam": "",
        "ifCode": "WEB",
        "mchNo": "726179",
        "mchOrderNo": "1JVOUPM2C1FGKKAY",
        "payOrderId": "631708196754194436",
        "state": 2,
        "successTime": 0,
        "wayCode": "",
        "channelUser": ""
    }

    # HiiCash 网关默认返回信息已经是按照键名首字母升序排序，如果你是手动获取的参数，需要将 body 参数按照键名升序排序
    body = {k: body[k] for k in sorted(body)}

    gateway_timestamp = headers.get("HiicashPay-Timestamp", None)
    gateway_nonce = headers.get("HiicashPay-Nonce", None)
    body_str = json.dumps(body, ensure_ascii=False, separators=(",", ":"))

    signature = generate_signature(gateway_timestamp, gateway_nonce, body_str, secret_key)
    gateway_signature = headers.get("HiicashPay-Signature", None)

    if signature == gateway_signature:
        print("校验成功")

        return {
            "returnCode": "success",
            "returnMsg": ""
        }

    else:
        print("校验失败")


if __name__ == "__main__":
    main()

注意

# 是一些框架在获取 body 的参数时，例如：PHP 的 Laravel
# 可能会因为网关传递的某些参数为空，从而把它转为 `null` 类型，这会导致签名计算错误
# 务必注意不能将空字段转为 null 类型，空字段的变量类型必须为 `string`
# 举例 ["extParam": ""] 不能是 ["extParam": null]

---

网关支付

---

支付验证

用户通过该接口进行支付验证，如果是Voucher，验证通过后直接扣款，如果是用户，则返回需要填入的验证码类型

请求URL：/pay/order/verify

请求方式：POST

请求类型：application/json

请求参数

字段名	变量名	必填	类型	示例值	描述
支付订单号	payOrderId	是	String(30)	12021022311124442600	支付系统订单号
渠道用户	channelUser	是	String	882010423410394	渠道用户号 voucher卡号或者user_id
验证数据	verifyData	否	String(30)	密码

示例数据

{
  "payOrderId": "202306181104177050002",
  "channelUser": "8818614321423414",
  "verifyData": "password"
}

返回参数

字段名	变量名	必填	类型	示例值	描述
返回状态	code	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	msg	否	String(128)	参数格式校验错误	具体错误原因，例如：签名失败、参数格式校验错误
返回数据	data	否	String(512)	{}	返回验证数据,json格式

Data数据格式

字段名	变量名	必填	类型	示例值	描述
验证类型	verifyType	是	int	0	验证类型 1-邮箱验证码 2-Google验证器

示例数据

{
  "code": 0,
  "data": {
    "verifyType": 1,
  },
  "msg": "SUCCESS"
}

申请扣款

用户通过该接口进行申请扣款

请求URL：/pay/order/billing

请求方式：POST

请求类型：application/json

请求参数

字段名	变量名	必填	类型	示例值	描述
支付订单号	payOrderId	是	String(30)	12021022311124442600	支付系统订单号
验证数据	verityData	是	String(30)	验证码内容

示例数据

{
  "payOrderId": "202306181104177050002",
  "verityData": "123456"
}

返回参数

返回状态	code	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	msg	否	String(128)	参数格式校验错误	具体错误原因，例如：签名失败、参数格式校验错误
返回数据	data	否	String(512)	{}	返回验证数据,json格式

示例数据

{
  "code": 0,
  "data": {
  },
  "msg": "SUCCESS"
}

如需使用以下余额支出接口，请先在 商户后台 -> 设置 -> API 设置 启用 API扣款功能，该功能默认关闭。再次提醒，如果应用密钥不慎泄漏可能会造成您的余额损失。

创建代金券

商户通过该接口进行创建代金券，费用会自动从商户余额中支出

请求URL：/voucher/create

请求方式：POST

请求类型：application/json

请求参数

字段名	变量名	必填	类型	示例值	描述
金额	amount	是	Int	500	创建代金券面值，最小 500($5)，最大20000($200)
数量	quantity	是	Int	1	创建代金券数量，单次最少创建1张，最大100张
是否激活	isActive	否	Bool	True/False	是否激活，默认不激活，不激活情况下只返回激活码，需要手动激活一次才能使用，激活的情况下返回代金券卡号和卡密

示例数据

{
    "amount": 500,
    "quantity": 1,
    "isActive": False
}

返回参数

返回状态	code	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	msg	否	String(128)	参数格式校验错误	具体错误原因，例如：签名失败、参数格式校验错误
返回数据	data	否	String(512)	{}	返回验证数据,json格式
代金券信息	data -> vouchers	是	Array		数组形式返回多组代金券

示例数据

{
    "code": 0,
    "message": "Ok",
    "data": {
        "vouchers": [
            {
                "ActiveCode": "910b782692546c55f8f7998f9d4ade2e9", // 激活码
                "VoucherNumber": "", // 代金券卡号
                "VoucherPassword": "" // 代金券卡密
            }
        ]
    }
}

创建转账

商户通过该接口进行想其他 HiiCash 账户转账，费用会自动从商户余额中支出

请求URL：/wallet/transfer

请求方式：POST

请求类型：application/json

请求参数

字段名	变量名	必填	类型	示例值	描述
金额	amount	是	Int	500	转账金额，单次转账最小金额 200($2)，最大不限
账户号	accountNo	是	Int	8888888888888888	接收方 16 位账户号
附言	memo	否	String	测试转账	转账备注信息

示例数据

{
    "amount": 499,
    "accountNo": 8888888888888888,
    "memo": "测试转账"
}

返回参数

返回状态	code	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	msg	否	String(128)	参数格式校验错误	具体错误原因，例如：签名失败、参数格式校验错误
返回数据	data	否	String(512)	{}	返回验证数据,json格式
转账订单号	data -> transactionId	是	String(128)		转账订单号

示例数据

{
    "code": 0,
    "message": "Ok",
    "data": {
        "transactionId": 543288130526150661 // 转账订单号
    }
}