您当前的位置:首页>支付接口相关>免签接口

第三步: API说明[免签通道教程]

来源:免签通道教程 发布时间:2021-06-29 18:42:08作者:免签接口热度:14 ℃

本文主要面向有一定开发基础的用户查阅对接,请仔细接口文档,如有疑问可以下载支付DEMO查看对接代码样例。>前往下载<

接口支持收款码通道、签约接口通道支付方式。

免签和签约接口相同,不同处为创建支付订单参数“支付方式 payType”的传值,为了方便查看,特此分开。

免签:https://doc.zhifu.fm/d/v/1.0/1/26.html

签约:https://doc.zhifu.fm/d/v/1.0/11/64.html

接口测试工具:Postmam 或在线工具 https://getman.cn/ 

1.创建支付订单


接口地址:
https://zfapi.nnt.ltd/api/startOrder 
http://zfapi.nnt.ltd/api/startOrder 
请求方法:POST
参数传递:Query Params参数需在请求URL传参
请求参数说明(注意:以下参数名称字母大小写敏感

在线请求示例:https://getman.cn/?s=c38269fd214b4ce6b7da8c67e8d4b490 

参数
参数含义
必填
说明
merchantNum
商户号,用户唯一标识

商户号,支付FM后台【用户中心】处获取
orderNo
商户订单号

仅允许字母或纯数字,建议不超过32字符,不能有中文
amount
订单金额

请求的支付价格(单位:元),最多小数点后保留2位
returnType接口返回类型

参数可选:page。页面form表单提交方式可用,不传默认返回json格式(见2.订单创建成功),传入page后直接重定向到付款二维码。

部分开发语言非页面form表单直接提交的有可能无法重定向,请自行解析json进行跳转。

notifyUrl
异步通知地址

http(s)开头的公网地址。商户业务系统用来接收支付结果通知数据的回调地址,通知url必须为外网可访问的url且不能携带参数。

returnUrl支付成功后,跳转到的地址

http(s)开头的公网地址。支付成功后跳转到的地址,仅跳转作用,一般为业务系统的支付成功提示或者订单中心等。不参与签名。请注意该地址是跳转地址,请勿用此地址作为支付成功验证

payType支付方式

支付方式,请根据所需对接通道正确传值,参数请查看payType可选值说明

attch附加信息原样返回
subject商品标题选填,商品标题,100字符以内
body商品描述选填,商品描述,200字符以内
sign签名【md5(商户号+商户订单号+支付金额+异步通知地址+接入密钥)】

通过MD5加密指定的值拼接计算得出的签名值。

签名值=md5(商户号+商户订单号+支付金额+异步通知地址+接入密钥);其中“+”表示字符串拼接。

接入密钥在支付FM商户后台【用户中心】处获取。

payType值说明

参数
参数含义
通道类型

wechat

微信收款码免签通道

alipay

支付宝收款码
unipay云闪付收款码
qujie.qrcode趣街小二商家版收款码
alipaysign支付宝网站支付接口(PC&WAP)签约通道
alipay-facetoface支付宝当面付
wxpayh5微信支付H5
wxpaynative微信支付Native
wxpayjsapi
微信支付JSAPI


订单创建成功

当参数“returnType”不传值或者值不为“page”时候,订单支付创建成功后,支付FM会同步返回如下格式JSON数据。

参数
参数含义
必填
说明
code状态码订单状态码【200代表正常】
msg错误信息错误状态下返回错误信息utf-8编码数据
data
数据内容
JSONObject


data内容

参数
参数含义
必填
说明
id
平台订单号

支付FM平台生成的订单号
payUrl

支付链接

正常状态下返回支付跳转路径,跳转到该路径即可支付。如您的业务系统为APP请调用手机浏览器访问此链接,不建议在APP内直接访问。


请求示例

此处罗列一些常用请求的部分代码供参考,完整代码可以参考demo篇章。备注:java系统若使用老版hutool工具请求https接口可能会报错需升级到JDK11或使用http协议请求或使用demo中方法请求。

示例1
非FORM表单POST请求URL:
https://zfapi.nnt.ltd/api/startOrder?orderNo=20190629023134U93661199&amount=89&payType=wechat&merchantNum=tencent&sign=65a4949d97bc4e55aff2393370db09ed&notifyUrl=http://****/paySuccessNotice
示例2
form表单POST提交
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>跳转支付中……</title></head>
<body>
<form style="display:none" id="fPay" method="post" action="https://zfapi.nnt.ltd/api/startOrder">
<input name="merchantNum" type="text" value="$merchantNum"/>
    <input name="amount" type="text" value="$amount"/>
    <input name="payType" type="text" value="$payType"/>
    <input name="returnUrl" type="text" value="$returnUrl"/>
    <input name="notifyUrl" type="text" value="$notifyUrl"/>
    <input name="orderNo" type="text" value="$orderID"/>
    <input name="subject" type="text" value="$subject"/>
    <input type="hidden" name="returnType" value="$returnType"/>
    <input name="sign" type="text" value="$sign"/>
</form>
<script type="text/javascript">
 // 自动提交也可以手动通过按钮触发表单提交 
</script>
</body>
</html>

自动提交    图片.png

示例3
PHP构造curl方式提交 
(未验证,仅供参考)
$url=接口地址; 
$query_data="orderNo=20190629023134U93661199&amount=1&payType=wechat&merchantNum=tencent&sign=febf5e0e46fcc6bcadfc94c5fb46b0c2&notifyUrl=https://****/paySuccessNoticeTest";
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $query_data); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
return array($httpCode, $response);
示例4
JAVA,完整参考demo
        Map<String, Object> paramMap = new HashMap<>();// post请求的参数
        paramMap.put("merchantNum", merchantNum);
        paramMap.put("orderNo", orderNo);
        paramMap.put("amount", amount);
        paramMap.put("notifyUrl", notifyUrl);
        paramMap.put("returnUrl", returnUrl);
        paramMap.put("payType", payType);
        paramMap.put("attch", attch);
        paramMap.put("sign", sign);
        paramMap.put("subject", "测试商品标题");
        paramMap.put("body", "测试商品说明");
        String paramStr = HttpUtil.toParams(paramMap);
        System.out.println(paramStr);
        HttpClient httpclient = HttpClientBuilder.create().build();
        HttpPost httpost = new HttpPost(url + "?" + paramStr); // 设置响应头信息
        HttpResponse retResp;
        String result;
        JSONObject ret = new JSONObject();
        try {
            retResp = httpclient.execute(httpost);
            result = EntityUtils.toString(retResp.getEntity(), "UTF-8");
            System.out.println(result);
        }
        catch (ClientProtocolException e1) {
            e1.printStackTrace();
        }
        catch (IOException e1) {
            e1.printStackTrace();
        }catch (ParseException e1) {
            e1.printStackTrace();
        }
示例5
php的file_get_contents方式请求
(未验证,仅供参考)
$url = "https://zfapi.nnt.ltd/api/startOrder?orderNo=20190629023134U93661199&amount=89&payType=wechat&merchantNum=tencent&sign=65a4949d97bc4e55aff2393370db09ed&notifyUrl=http://****/paySuccessNotice"              
$opt = array('http' => array('method' => 'POST'));
$context=stream_context_create($opt);
$file_contents = file_get_contents($url,false, $context);
echo $file_contents;
返回示例
成功情况:
{"msg":"success",
"code":200,
"timestamp":1584597152228,
"data":{"id":"1240516484711579648",
"payUrl":"https://zfm.nnt.ltd/pay?orderNo=1240516484711579648"}
}
其他情况:
{
    "success": false,
    "msg": "app监控回调失败,找不到对应通道金额的订单",
    "code": 500,
    "timestamp": 1584413776852,
    "data": null
}
2.支付成功异步回调接口当订单支付成功后,支付FM会向您传入的notifyUrl 地址推送数据,当您收到后请同步返回字符串success,小写的这七个字母给我们,否则我们会累计通知3次到地址notifyUrl,系统会记录返回异常的部分记录,在失败详情中供查阅。

注意:thinkphp返回 success 时候一定要关闭调试模式,因为调试模式会额外返回一串html有可能导致平台判定未收到。notifyUrl被支付FM服务器请求如返回Read timed out等网络不通畅的情况只会通知一次。

这是get请求,您可以按照下述的参数规范组装请求串,调试您的接口,形如:notifyUrl地址?state=1&merchantNum=XX&orderNo=XX&amount=XX&sign=XX&actualPayAmount=XX

接口地址:订单发起时候notifyUrl传入地址

请求方法:GET
参数传递:Query Params参数在请求URL传参

请求参数说明

参数
参数含义
必填
说明

merchantNum

商户号


orderNo

商户订单号

即发起支付订单传入的订单号

platformOrderNo支付FM平台订单号平台生成的唯一订单号
amount订单金额最多保留小数点后2位
actualPayAmount实际支付金额最多保留小数点后2位。当商户使用免签通道的固定收款码或通用收款码被未支付订单占用时,系统会自动展示通用收款码并做金额上下浮动后,此时客户支付的金额。
attch商户传入的附加信息商户传入则原样传回
state付款成功状态1:付款成功
payTime付款时间标准日期时间格式,精确到秒:yyyy-MM-dd HH:mm:ss 
sign签名【md5(付款成功状态state的值+商户号merchantNum的值+商户订单号orderNo的值+订单金额amount的值+接入密钥)】


接收方式

此处罗列一些业务系统侧接收回调接口的部分代码供参考,完整代码可以参考demo篇章。

JAVA:
@ResponseBody
@GetMapping("/SuccessNotice")
public String SuccessNotice(@RequestParam Map<String, String> map) {}
或者
public String SuccessNotice(HttpServletRequest request) {
     Map requestParams = request.getParameterMap();
}

PHP:
$merchantNum = '您的商户号';
$key = '您的接入密钥';
$sign = sign(array($_GET@['state'], $merchantNum, $_GET@['orderNo'], $_GET@['amount'], $key));
# 鉴权
if($merchantNum==$_GET@['merchantNum'] && $sign == $_GET@['sign']) {
//鉴权通过后的业务代码
}
/**
*签名方法
*/
function sign($data_arr) {
       return md5(join('',$data_arr));
};


回调参数示例
 http://notifyUrl地址?amount=0.2&orderNo=T1584936360806&actualPayAmount=0.2&payTime=2020-03-23 12:51:48&platformOrderNo=1241950691694477312&merchantNum=shanghuhao&sign=4115128010ccff25665524dfd711ffaf&state=1
MD5签名示例支付DEMO中有完整说明和建议使用的工具包,以下只是签名示例(JAVA),其他语言可以用示例参数签名,签名结果一致表示签名函数是可用的

供技术调试对比MD5算法用:abc123456的MD5加密串:大写:0659C7992E268962384EB17FAFE88364,小写:0659c7992e268962384eb17fafe88364

实际对接有问题可以联系客服,免费安排技术协助。

package ltd.nnt.zhifu.test;

import java.math.BigInteger;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
 
public class MD5Utils {
    /**
     * 使用md5的算法进行加密
     */
    public static String md5(String plainText) {
        byte[] secretBytes = null;
        try {
            secretBytes = MessageDigest.getInstance("md5").digest(
                    plainText.getBytes());
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException("没有md5这个算法!");
        }
        String md5code = new BigInteger(1, secretBytes).toString(16);// 16进制数字
        // 如果生成数字未满32位,需要前面补0
        for (int i = 0; i < 32 - md5code.length(); i++) {
            md5code = "0" + md5code;
        }
        return md5code;
    }
 
    public static void main(String[] args) {
        System.out.println(md5("abc123456"));
    }
 
}


本站相关源码推荐

转载请注明来源网址:https://www.bdjcwl.cn/mqjk/817.html本文标题:第三步: API说明[免签通道教程]