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
trade_type 支付场景 String(16) 签约支付宝2.0时必填,固定值:“WEB”
goods_detail 商品详情 String(128) 商品详情
attach 附加参数 String(128) 附加的其他参数
nonce_str 随机字符串 String(32) 增加安全性
client_ip 客户端IP地址 String(32) 发起支付的用户客户端IP
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)
收银台支付
提交方式:GET 通过拼接请求地址和请求参数生成支付链接,然后直接在相应端跳转链接进行唤醒微信或者支付宝支付
收银台方式同样是通过 JSAPI 方式发起的支付,收银台是JSAPI的简化版,相当于我们在服务端做好了JSAPI的开发(显示我们服务端URL地址),只需要跳转过来就行,适用于微信webview环境,签约支付宝2.0请用“支付宝WAP支付”。
请求地址:(微信: 接入网关/pay/cashier, 支付宝1.0: 接入网关/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) 附加的其他参数
client_ip 客户端IP地址 String(32) 发起支付的用户客户端IP
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域名)
client_ip 客户端IP地址 String(32) 发起支付的用户客户端IP
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) 支付跳转链接(商户界面直接跳转到该链接即可唤起微信支付,支付完成后跳转问题请查看:https://pay.weixin.qq.com/wiki/doc/api/H5.php?chapter=15_4的常见问题->回调页面)
获取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) 通知回调地址
redirect_url 跳转地址 String(128) 支付成功后的跳转地址
attach 附加参数 string(128) 附加的其他参数
client_ip 客户端IP地址 String(32) 发起支付的用户客户端IP
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) 附加的其他参数
client_ip 客户端IP地址 String(32) 发起支付的用户客户端IP
nonce_str 随机字符串 string(32) 用于验证
sign 签名 string(64) 请参考下面签名算法
返回参数:支付后自动返回,后端判断订单状态。
支付宝2.0 WAP支付
支付宝2.0专用,1.0手机端请用收银台支付
提交方式: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”
trade_type 支付场景 String(16) WAP支付此处传“WAP”
goods_detail 商品详情 String(128) 商品详情
attach 附加参数 String(128) 附加的其他参数
nonce_str 随机字符串 String(32) 增加安全性
client_ip 客户端IP地址 String(32) 发起支付的用户客户端IP
redirect_url 跳转地址 String(128) 支付成功后的跳转地址
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)
mweb_url 支付跳转链接 String(128) 支付跳转链接(商户界面直接跳转到该链接即可唤起支付宝支付)
APP支付
提交方式:POST
(暂只支持微信支付)商户在自己的APP中发起支付请求,并跳转到支付应用中进行支付,支付成功后跳转回商户APP。
请求格式: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 目前暂支持支付宝
trade_type 支付方式 String(16) 此处传“APP”
goods_detail 商品详情 String(128) 商品详情
attach 附加参数 String(128) 附加的其他参数
nonce_str 随机字符串 String(32) 增加安全性
client_ip 客户端IP地址 String(32) 发起支付的用户客户端IP
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)
app_request APP请求参数 String(1024) 根据此参数值,通过微信的OPENSDK唤起支付
分账接口(测试中,未正式上线)
标记分账订单,上传openid或MCHID,自动实现订单分账
支持扫码(/pay/payment),H5支付(/pay/payment),jspai支付(/pay/jsapi),小程序支付(/pay/mini)
请求格式:application/json
请求参数:
参数名称 参数含义 字段类型 是否必填 参数说明
profit_sharing 标识分账订单 boolean 是否为分账订单,默认false
profit_sharing_detail 分账详情 Array 若为分账订单,可制定分账接收者信息,自动进行分账;数据为json数组
type 分账接收方类型 string(32) 分账接收方类型,枚举值: MERCHANT_ID:商户 PERSONAL_OPENID:个人
account 分账接收方账号 string(128) 分账接收方账号: 类型是MERCHANT_ID时,是商户ID 类型是PERSONAL_OPENID时,是个人openid(根据openid接口获取)
amount 分账金额 int 分账金额,单位为分,只能为整数,不能超过原订单支付金额及最大分账比例金额。
description 分账描述 string(128) 分账的原因描述,分账账单中需要体现。
返回参数:支付后自动返回,后端判断订单状态。
通知回调
提交方式: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) 平台返回订单号
transaction_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)
退款成功通知回调
用户申请退款成功后,平台会根据退款请求中的notify_url进行回调,该地址需要确保外网可访问,平台会将参数以json方式,POST到商户的url地址
回调参数
参数名称 参数含义 字段类型 是否必填 参数说明
return_code 返回码 String(32) 返回码 success:成功; fail:失败
return_msg 返回结果 String(16) 返回结果描述
err_code 错误码 String(32) 错误码,仅到return_code为fail时有值
err_msg 错误的描述信息 String(128) 错误的描述信息
nonce_str 随机字符串 String(32) 随机字符串
sign 签名 String(64) 签名字符串
mchid 商户号 String(32) 商户号
refund_id 平台退款单号 String(32) 平台退款单号
out_refund_id 商户退款单号 String(32) 商户退款单号
refund_fee 退款金额 Integer 退款金额
refund_status 退款状态 String(128) SUCCESS:退款成功 REFUNDCLOSE:退款关闭 PROCESSING:处理中 EXCEPTION:退款异常
refund_time 退款日期 String(32) 退款成功时间:日期格式:yyyyMMddHHmmss
order_id 订单id String(32) 平台订单id
out_trade_no 用户订单号 String(32) 用户订单号
total_fee 订单总金额 Integer 订单总金额
返回参数:
商户处理完成后,直接返回success字符串给平台即可,注意是success小写
投诉信息查询
通过投诉信息查询接口,可查询到商户的投诉记录,状态等,目前只能查微信投诉。
请求地址:https://admin.xunhuweb.com/pay/complaint/query
请求参数
参数名称 参数含义 字段类型 是否必填 参数说明
mchid 商户号 String(32) 商户号
nonce_str 随机字符串 String(32) 随机字符串
sign 签名字符串 String(64) 签名字符串
begin_time 查询时间 String(32) 查询最早时间,最多支持查询前30天内的投诉信息;日期字符串格式为:yyyyMMddHHmmss
返回参数:
参数名称 参数含义 字段类型 是否必填 参数说明
return_code 返回码 String(32) 返回码 success:成功; fail:失败
return_msg 返回结果描述 String(128) 返回结果描述
err_code 错误码 String(32) 错误码,仅到return_code为fail时有值
err_msg 错误的描述信息 String(128) 错误的描述信息
nonce_str 随机字符串 String(32) 随机字符串
sign 签名字符串 String(64) 签名字符串
mchid 商户号 String(32) 商户号
items 投诉信息集合 Array 集合内容:
order_id string(32) 支付平台订单号
out_trade_no string(32) 商户订单号
total_fee int(16) 订单金额(单位为分)
transaction_id string(32) 官方交易ID
complaint_time string(32) 投诉时间 日期字符串格式为:yyyyMMddHHmmss
payer_phone string(256) 投诉人联系方式
complaint_detail string(300) 投诉描述
complaint_state string(32) 投诉单状态 枚举值: PAYER_COMPLAINTED:用户已投诉 FROZENED:交易已冻结 FROZEN_FINISHED:冻结已结束 PAYER_CANCELED:用户已撤诉 MERCHANT_REFUNDED:商户已退款 SYSTEM_REFUNDED:系统(微信支付)已退款 MANUAL_UNFROZEN:人工(微信支付运营人员)手动解冻
modify_time string(32) 最后修改时间 日期字符串格式为:yyyyMMddHHmmss
签名生成
签名步骤:
第一步,将所有发送或者接收到的数据为集合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;
	}
在线客服系统