API开发文档简介
本文阅读对象:使用 Xunhupay 商户自服务系统的技术架构师、研发工程师、系统运维工程师。通过本文档,商户可了解 Xunhupay 接入的技术、接入的产品业务、接入的流程、接入规范等信息,以便于商户顺利完成接入工作。
接入网关
https://admin.xunhuweb.com
扫码支付
提交方式:POST
请求格式:application/json
请求地址: 接入网关/pay/payment
请求参数:
参数名称 参数含义 字段类型 是否必填 参数说明
mchid 商户号 String(32) 平台分配商户号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
total_fee 订单金额 int(16) 单位:分
body 商品名称 String(128) 商品描述
notify_url 回调地址 String(128) 通知回调地址
type 支付类型 String(16) (alipay:支付宝,wechat:微信)不填默认为wechat
goods_detail 商品详情 String(128) 商品详情
attach 附加参数 String(128) 附加的其他参数
nonce_str 随机字符串 String(32) 增加安全性
sign 签名 String(64) 请查看签名算法
返回值:
参数名称 参数含义 字段类型 是否必填 参数说明
return_code 返回码 String(32) (success:成功;fail:失败)
return_msg 结果描述 int(16) 返回信息描述
err_code 错误码 String(32) 仅当return_code为fail时有值
err_msg 错误描述 String(128) 错误的描述信息
nonce_str 随机字符串 String(32)
sign 签名字符串 String(64)
goods_detail 商品详情 String(128) 商品详情
mchid 商户号 String(32) 平台分配商户号
order_id 平台返回订单号 String(32) 平台返回订单号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
total_fee 订单金额 int(16)
code_url 支付二维码 String(128)
收银台支付
收银台方式同样是通过 JSAPI 方式发起的支付,只是简化了开发步骤和流程,适用于微信webview环境。
请求地址:(微信: 接入网关/pay/cashier, 支付宝: 接入网关/alipaycashier)
请求参数:
参数名称 参数含义 字段类型 是否必填 参数说明
mchid 商户号 String(32) 平台分配商户号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
total_fee 订单金额 int(16) 单位:分;不传金额就是手动输入金额
body 商品名称 String(128) 商品描述
notify_url 回调地址 String(128) 通知回调地址
redirect_url 跳转地址 String(128) 支付成功后的跳转地址
type 支付类型 String(16) (alipay:支付宝,wechat:微信)不填默认为wechat
attach 附加参数 String(128) 附加的其他参数
nonce_str 随机字符串 String(32) 增加安全性
sign 签名 String(64) 请查看签名算法
返回值:
请求成功无返回值
微信H5支付
提交方式:POST
请求格式:application/json
请求地址接入网关/pay/payment
请求参数:
参数名称 参数含义 字段类型 是否必填 参数说明
mchid 商户号 String(32) 平台分配商户号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
total_fee 订单金额 int(16) 单位:分
body 商品名称 String(128) 商品描述
goods_detail 商品详情 string(128) 商品详情
attach 附加参数 string(128) 附加的其他参数
notify_url 回调地址 String(128) 通知回调地址
type 支付类型 String(16) 固定值"wechat"
trade_type 支付类型(端) String(16) 固定值"WAP"
wap_url 跳转域名 String(128) WAP跳转域名(需与发起支付的域名保持一致,请联系管理员配置H5域名)
wap_name 网站名称 String(128) 网站名称(建议与网站名称一致)
nonce_str 随机字符串 String(32) 增加安全性
sign 签名 String(64) 请查看签名算法
返回值:
参数名称 参数含义 字段类型 是否必填 参数说明
return_code 返回码 String(32) (success:成功;fail:失败)
return_msg 结果描述 int(16) 返回信息描述
err_code 错误码 String(32) 仅当return_code为fail时有值
err_msg 错误描述 String(128) 错误的描述信息
nonce_str 随机字符串 String(32)
sign 签名字符串 String(64)
goods_detail 商品详情 String(128) 商品详情
mchid 商户号 String(32) 平台分配商户号
order_id 平台返回订单号 String(32) 平台返回订单号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
total_fee 订单金额 int(16)
mweb_url 支付链接 String(128) 支付跳转链接(商户界面直接跳转到该链接即可唤起微信支付)
获取openId
通过jsapi发起支付时,需提供用户微信针对当前服务商的openid;需根据如下要求拼装url地址,然后直接跳转到该地址,获取成功后,会自动重定向至用户指定地址,并附带openid参数
请求地址:/pay/openid
请求参数:
参数名称 参数含义 字段类型 是否必填 参数说明
mchid 商户号 String(32) 商户号
redirect_url 跳转路径 string(128)
返回参数:
参数名称 参数含义 字段类型 是否必填 参数说明
openid 返回码 string(32) 用户微信openid
微信JSAPI支付
用户在微信端浏览商户页面,选择商品后,直接调起微信支付进行付,调用该接口时,需要获取openid,商户根据该接口返回值中的jsapi,在界面上直接调用微信的jsapi接口进行支付,需要配置授权支付目录请联系管理员添加授权目录。
请求地址:/pay/jsapi
请求格式:application/json
请求参数:
参数名称 参数含义 字段类型 是否必填 参数说明
mchid 商户号 String(32) 商户号
openid 用户微信openid string(32) 用户微信openid
total_fee 订单金额 int(16) 单位:分
out_trade_no 商户订单号 string(32) 用户端自主生成的订单号
body 商品描述 string(128) 商品描述
goods_detail 商品详 string(128) 商品详情
notify_url 通知回调地址 string(128) 通知回调地址
attach 附加参数 string(128) 附加的其他参数
nonce_str 随机字符串 string(32) 用于验证
sign 签名 string(64) 请参考下面签名算法
返回参数:
参数名称 参数含义 字段类型 是否必填 参数说明
return_code 返回码 String(32) (success:成功;fail:失败)
return_msg 结果描述 int(16) 返回信息描述
err_code 错误码 String(32) 仅当return_code为fail时有值
err_msg 错误描述 String(128) 错误的描述信息
nonce_str 随机字符串 String(32)
sign 签名字符串 String(64)
goods_detail 商品详情 String(128) 商品详情
mchid 商户号 String(32) 平台分配商户号
order_id 平台返回订单号 String(32) 平台返回订单号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
total_fee 订单金额 int(16)
jsapi 参数类别 string(512) 页面调起微信支付时的请求参数
微信小程序支付
商户小程序中下单,小程序跳转到 迅虎支付 小程序,支付后返回。参考小程序demo
请求地址:/pay/mini
请求格式:application/json
请求参数:
参数名称 参数含义 字段类型 是否必填 参数说明
mchid 商户号 String(32) 商户号
total_fee 订单金额 int(16) 单位:分
out_trade_no 商户订单号 string(32) 用户端自主生成的订单号
body 商品描述 string(128) 商品描述
goods_detail 商品详 string(128) 商品详情
notify_url 通知回调地址 string(128) 通知回调地址
attach 附加参数 string(128) 附加的其他参数
nonce_str 随机字符串 string(32) 用于验证
sign 签名 string(64) 请参考下面签名算法
返回参数:支付后自动返回,后端判断订单状态。
通知回调
提交方式:POST
用户支付成功后,平台会根据订单中用户的notify_url进行回调,该地址需要确保外网可访问,平台会将参数以json方式,POST到商户的url地址
回调参数:
参数名称 参数含义 字段类型 是否必填 参数说明
return_code 返回码 String(32) (success:成功;fail:失败)
return_msg 结果描述 int(16) 返回信息描述
err_code 错误码 String(32) 仅当return_code为fail时有值
err_msg 错误描述 String(128) 错误的描述信息
nonce_str 随机字符串 String(32)
sign 签名字符串 String(64)
mchid 商户号 String(32) 平台分配商户号
order_id 平台返回订单号 String(32) 平台返回订单号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
total_fee 订单金额 int(16)
status 支付状态 String(32) complete:支付成功(目前仅支付成功后会回调通知)
time_end 支付时间 Date
attach 附加属性 String(128)
返回参数:
商户处理完成后,直接返回success字符串给平台即可,注意是success小写
订单查询
提交方式:POST
请求地址: 接入网关/pay/query
参数名称 参数含义 字段类型 是否必填 参数说明
mchid 商户号 String(32) 平台分配商户号
out_trade_no 商户订单号 String(32) (与平台订单号必填其一
order_id 平台返回订单号 String(32) (与商户订单号必填其一)
nonce_str 随机字符串 String(32) 增加安全性
sign 签名 String(64) 请查看签名算法
返回值
参数名称 参数含义 字段类型 是否必填 参数说明
return_code 返回码 String(32) (success:成功;fail:失败)
return_msg 结果描述 int(16) 返回信息描述
err_code 错误码 String(32) 仅当return_code为fail时有值
err_msg 错误描述 String(128) 错误的描述信息
nonce_str 随机字符串 String(32)
sign 签名字符串 String(64)
mchid 商户号 String(32) 平台分配商户号
order_id 平台返回订单号 String(32) 平台返回订单号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
total_fee 订单金额 int(16)
status 订单状态 String(32) to_be_paid:已发起
complete:支付成功
refunding退款中
refunded:已退款
closed:已关闭
error:异常
cancel:已撤销
time_end 支付时间 Date
attach 附加属性 String(128)
退款
提交方式:POST
提交地址:接入网关/pay/refund
参数名称 参数含义 字段类型 是否必填 参数说明
mchid 商户号 String(32) 平台分配商户号
order_id 平台返回订单号 String(32) 平台返回订单号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
refund_desc 退款原因 String(128) 退款原因
notify_url 回调地址 String(128) 通知回调地址
nonce_str 随机字符串 String(32) 增加安全性
sign 签名 String(64) 请查看签名算法
返回值
参数名称 参数含义 字段类型 是否必填 参数说明
return_code 返回码 String(32) (success:成功;fail:失败)
return_msg 结果描述 int(16) 返回信息描述
err_code 错误码 String(32) 仅当return_code为fail时有值
err_msg 错误描述 String(128) 错误的描述信息
nonce_str 随机字符串 String(32)
sign 签名字符串 String(64)
mchid 商户号 String(32) 平台分配商户号
order_id 平台返回订单号 String(32) 平台返回订单号
out_trade_no 商户订单号 String(32) 用户端自主生成的订单号
refund_no 退款单号 String(128)
签名生成
签名步骤:
第一步,将所有发送或者接收到的数据为集合M,将集合M内非空参数值的参数按照参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA
特别注意以下重要规则:
◆ 参数名ASCII码从小到大排序(字典序);
◆ 如果参数的值为空不参与签名;
◆ 参数名区分大小写;
◆ 验证调用返回或微信主动通知签名时,传送的sign参数不参与签名,将生成的签名与该sign值作校验。
第二步,在stringA最后拼接上秘钥得到stringSignTemp字符串,并对stringSignTemp进行MD5运算,转换成大写,得到sign值。
签名生成示例(PHP):
  public static function generate_xh_hash(array $datas,$hashkey){
        ksort($datas);
        reset($datas);

        $pre =array();
        foreach ($datas as $key => $data){
            if(is_null($data)||$data===''){
                continue;
            }
            if($key=='sign'){
                continue;
            }
            $pre[$key]=$data;
        }

        $arg  = '';
        $qty = count($pre);
        $index=0;

        foreach ($pre as $key=>$val){
            $arg.="$key=$val";
            if($index++<($qty-1)){
                $arg.="&";
            }
        }
        return strtoupper(md5($arg.'&key='.$hashkey));
    }
支付链接获取(PHP)
HTTP_POST方式(扫码支付):
 public function http_post_json($url, $jsonStr){
	    $ch = curl_init();
	    curl_setopt($ch, CURLOPT_POST, 1);
	    curl_setopt($ch, CURLOPT_URL, $url);
	    curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonStr);
	    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	            'Content-Type: application/json; charset=utf-8',
	            'Content-Length: ' . strlen($jsonStr)
	        )
	    );
	    $response = curl_exec($ch);
	    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
	    curl_close($ch);
	    return $response;
	}
URL拼接方式(收银台支付):
 public function data_link($url,$datas){
		ksort($datas);
        reset($datas);
        $pre =array();
        foreach ($datas as $key => $data){
            if(is_null($data)||$data===''){
                continue;
            }
            if($key=='body'){
                continue;
            }
            $pre[$key]=$data;
        }
        $arg  = '';
        $qty = count($pre);
        $index=0;
		 foreach ($pre as $key=>$val){
		 		$val=urlencode($val);
			 	$arg.="$key=$val";
	            if($index++<($qty-1)){
	                $arg.="&";
	            }
        }
        return $url.'?'.$arg;
	}