本平台接口兼容易支付体系的开发规范,请求参数规范如下。如果您的网站系统后台已经集成易支付插件可以0代码开发快速使用接口。 也可以根据规范自行对接。
易支付插件如何使用 支付FM接口任意网站支付?:https://www.bilibili.com/video/BV1Vp421y7iF
易支付插件中使用示例操作:https://www.bilibili.com/video/BV1F54y1w7FR
接口主要参数值对应关系如下图,以下参数值均在支付FM商户后台【用户中心】处查看。
通过“支付方式关联”设置可以无需修改代码,0代码开发使用支付FM的其他支付方式,当然这些方式必须是你已经设置了收款账号的。
商户ID ➡️ 商户号(图示①位置)
接口URL地址 ➡️ V2接口地址(也就是旧版本的兼容接口地址(图示②位置))
商户密钥KEY➡️接入密钥(图示③位置)
接口URL地址支持
HTTP
与HTTPS
协议,建议使用https开头的接口地址。如果你的站点开启了https请将接口地址开头的http改为https即可。否则有可能浏览器出现如下图的不安全提示。
对接前置工作
一句话概括
:想用什么支付方式,您需要有对应的收款账号,然后配置到支付FM后台对应位置,最后技术对接我们接口。如果你的网站后台有支付FM的插件或 易支付系列的插件,可以不需要对接接口API,配置对应接口参数就可以。
1. 请亲爱的您要耐心看文档,文档为我们精心编写,可以解决您99%遇到的问题,文档有图文对照操作更快捷。
2. 请先看下支付方式效果说明,了解您想用且能用的支付方式的顾客支付效果。
3. 根据对接步骤完成相应的支付方式的收款号配置。
页面跳转支付
此接口可用于用户前台直接发起支付,使用form表单跳转或拼接成url跳转。
URL地址:【V2接口地址】
【V2接口地址】:
在支付FM商户后台【用户中心】处可查看
,一般有些系统的接口地址配置时候不用带/
,如果请求失败,请去掉 V2接口地址/
或 V2接口地址submit.php
示例:【V2接口地址】为http://api-1tecywsv9xc0.zhifu.fm.it88168.com/api/
, 填入插件报错,去掉尾部的/
修改为http://api-1tecywsv9xc0.zhifu.fm.it88168.com/api
试下,仍旧报错 再修改为http://api-1tecywsv9xc0.zhifu.fm.it88168.com/api/submit.php
试下。都试了还是报错请联系客服。请求方法:
POST
参数传递:Query
Content-Type:application/x-www-form-urlencoded
POST数据示例:pid={商户ID}&type={支付方式}&out_trade_no={商户订单号}¬ify_url={服务器异步通知地址}&return_url={页面跳转通知地址}&name={商品名称}&money={金额}&sign={签名字符串}&sign_type=MD5
页面跳转模式请求参数说明
URL地址:【用户中心】查看到的【V2接口地址】
,一般有些系统的接口地址配置时候不用带/
,如果请求失败,请去掉【V2接口地址】后的 /
或 【V2接口地址】后拼接 submit.php
请求方式:POST 或 GET(推荐POST,不容易被劫持或屏蔽)
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
商户ID | pid | 是 | String | 1001 | 对应支付FM平台的商户号。在支付FM商户后台【用户中心】处可查看,该值不是用户名。 |
支付方式 | type | 是 | String | alipay,wxpay | 支付宝、微信。默认关联免签收款码。通过用户中心的支付方式关联到具体的收款通道。免签类型 :收款手机需要安装监控APP挂机。签约类型 :需要开通对应的签约商户和支付产品。支付方式实际使用体验效果:https://docs.zhifux.com/read/zhifufm/paytype |
商户订单号 | out_trade_no | 是 | String | 20160806151343349 | 商户订单号。仅允许字母或纯数字,建议不超过32字符,不能有中文 |
异步通知地址 | notify_url | 是 | String | 域名/notify_url.php | 服务器异步通知地址,http(s)开头的网址。商户业务系统用来接收支付结果通知数据的回调地址,通知url必须为公网可访问的网址,且不能携带参数 ,收到通知后请根据规范返回成功标志,请根据通知参数规范使用Postmam等工具功能测试后传入。示例值: https://www.xxxx.com/payfm/payCalback.php |
跳转通知地址 | return_url | 是 | String | 域名/return_url.php | 支付FM后台订单状态为已支付才会跳转。支付完成后展示网址,有些支付方式在手机中无法跳转,所以请勿用此地址做验证或者业务强关联。200字符以内, 常见为业务系统的支付成功提示、订单中心、会员中心网址等,又称同步跳转地址。 为了安全考虑不要和notifyUrl值传入一样。 |
商品名称 | name | 是 | String | VIP会员 | |
商品金额 | money | 是 | number | 1.00 | 订单金额。请求的支付金额(单位:元),最多小数点后保留2位 |
网站名称 | sitename | 否 | String | 云任务 | |
业务扩展参数 | param | 否 | String | 没有请留空 | 支付后原样返回 |
签名字符串 | sign | 是 | String | 202cb962ac59075b964b07152d234b70 | 签名算法点此查看签名算法中的KEY 对应支付FM平台的“接入密钥”,在支付FM商户后台【用户中心】处可查看 |
签名类型 | sign_type | 是 | String | MD5 | 默认为MD5 |
POST接口支付
此接口可用于服务器后端发起支付请求,会返回支付二维码链接或支付跳转url。
URL地址:在支付FM商户后台【用户中心】处可查看到的“V2接口地址”
,一般有些系统的接口地址配置时候不用带/
,如果请求失败,请去掉“V2接口地址”后的 /
或 “V2接口地址”后拼接 mapi.php
请求方式:POST
请求参数说明:
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
商户ID | pid | 是 | Int | 1001 | |
支付方式 | type | 是 | String | alipay | 支付方式列表 |
商户订单号 | out_trade_no | 是 | String | 20160806151343349 | |
异步通知地址 | notify_url | 是 | String | http://域名/notify_url.php | 服务器异步通知地址 |
跳转通知地址 | return_url | 否 | String | http://域名/return_url.php | 页面跳转通知地址 |
商品名称 | name | 是 | String | VIP会员 | 如超过127个字节会自动截取 |
商品金额 | money | 是 | String | 1.00 | 单位:元,最大2位小数 |
用户IP地址 | clientip | 是 | String | 192.168.1.100 | 用户发起支付的IP地址 |
设备类型 | device | 否 | String | pc | 根据用户浏览器的UA判断,传入用户所使用的浏览器或设备类型,默认为pc设备类型列表 |
指定收款号 | payee | 否 | Sting | sj1 | 免签类型的手机编号/签约类型的微信系的账号标识/签约类型的支付宝系的支付宝账号 的值。 |
订单支付有效期 | payDuration | 否 | integer | 5 | 订单支付有效期,单位:分钟;默认值5,最大值15 |
回调请求求方式 | apiMode | 否 | String | POST | 默认 get请求方式回调通知;post_form:POST请求方式回调通知 |
业务扩展参数 | param | 否 | String | 没有请留空 | 支付后原样返回 |
签名字符串 | sign | 是 | String | 202cb962ac59075b964b07152d234b70 | 签名算法点此查看 |
签名类型 | sign_type | 是 | String | MD5 | 默认为MD5 |
返回结果(json):
字段名 | 变量名 | 类型 | 示例值 | 描述 |
---|---|---|---|---|
返回状态码 | code | Int | 1 | 1为成功,其它值为失败 |
返回信息 | msg | String | 失败时返回原因 | |
订单号 | trade_no | String | 20160806151343349 | 支付订单号 |
支付跳转url | payurl | String | https://page-admuk8xjk8ow.zhifu.fm.it88168.com/apiPay?orderNo=363823183490842624 | 如果返回该字段,则直接跳转到该url支付。顾客访问该网址就是对应不同支付方式的效果。如您的业务系统为APP,请调用手机浏览器访问此链接,不建议在APP内直接访问 |
二维码链接 | qrcode | String | https://page-admuk8xjk8ow.zhifu.fm.it88168.com/apiPay?orderNo=363823183490842624 | 如果返回该字段,则根据该url生成二维码 |
支付结果通知
注意:
1、notify_url就是您的业务系统的开放接口,请保证可以直接请求访问;不要做301、302等跳转;不要做登录验证等
2、系统会记录返回异常的部分记录,在商户订单的失败详情中供查阅
3、接口请求默认超时3s,所以您的接口执行时间要在3s内执行完毕
4、这是GET
请求,您可以参考请求示例拼接请求串,通过Postman调试您的接口
5、结果通知可能会多次请求,请务必参考下文特别提醒的建议处理
6、若多次回调异常,仍不按照接口规范进行调整,根据《支付FM用户条款》本公司将暂停或终止您对支付FM服务的使用特别提醒:
1、商户系统对于支付结果通知的内容一定要做签名验证,并校验返回的订单金额是否与商户侧的订单金额一致,防止数据泄漏导致出现“假通知”,造成资金损失。
2、当收到通知进行处理时,首先检查对应业务数据的状态,判断该通知是否已经处理过,如果没有处理过再进行处理,如果处理过直接返回结果成功暨字符串success。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。
通知类型:服务器异步通知(notify_url)
请求方式:GET
请求参数说明:
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
商户ID | pid | 是 | String | 1001 | 对应支付FM平台的商户号。在支付FM商户后台【用户中心】处可查看,该值不是用户名。 |
支付订单号 | trade_no | 是 | String | 20160806151343349021 | 聚合支付订单号 |
商户订单号 | out_trade_no | 是 | String | 20160806151343349 | 商户系统内部的订单号 |
支付方式 | type | 是 | String | alipay,wxpay | 支付方式列表 |
商品名称 | name | 是 | String | VIP会员 | |
商品金额 | money | 是 | String | 1.02 | |
支付状态 | trade_status | 是 | String | TRADE_SUCCESS | |
签名字符串 | sign | 是 | String | 202cb962ac59075b964b07152d234b70 | 签名算法见下文 |
签名类型 | sign_type | 是 | String | MD5 | 默认为MD5 |
通知IP列表
请需要设置IP地址请求访问白名单的用户注意设置防火墙等安全工具中的IP地址段,之前未有设置过IP段的用户不需做调整。
如果你的防火墙不支持掩码形式,直接一个个添加IP。如果掩码形式没有/27这种形式可以增加/8、/16、/24都可以 回调通知出口IP/掩码形式(IP地址范围)列表:
47.94.194.102/24(47.94.194.102-47.94.194.112)【2024年3月9日启用】
43.143.170.189/24(43.143.170.189-43.143.170.199) 【2024年4月29日启用】
39.107.193.170/24 (39.107.193.170-39.107.193.180) 【2024年4月30日启用】
47.104.216.190/24(47.104.216.190-47.104.216.195) 【2024年9月14日启用】
MD5签名算法
KEY 对应支付FM用户中心的 接入密钥
请对参数按照键名进行降序排序(a-z),sign sign_type 和空值不进行签名!。 排序后请操作参数生成或拼接一个url请求字符串 例如 a=b&c=d&e=f (Url值不能携带参数!不要进行urlencode) 再将拼接好的请求字符串与平台生成的Key进行MD5加密得出sign签名参数 md5 ( a=b&c=d&e=f + KEY ) (注意:+ 为各语言的拼接符!不是字符!),md5为小写