微信服务商-特约商户模式支付-支付成功回调页面不跳转问题 需要使用 特殊的处理 点金计划 商家小票 的模式

微信服务商-特约商户模式支付-支付成功回调页面不跳转问题 需要使用 特殊的处理 商家小票 的模式


商家小票 开发文档:


点金计划商家小票开发指引1.商家小票功能开通

“商家小票”是指商家为用户提供的订单详情,可展示不同业务场景下的服务性内容,例如取
餐码、剩余停车时长等。开通商家小票功能后,即可将商家页面嵌入到点金计划页面中。商家
小票示意图如下:

商家小票的开通步骤如下:

接下来具体介绍各步骤。

1.1 第一步:配置“商家小票链接”

点金计划页面上方为商家小票提供了一个 Iframe 框架,服务商在点金计划管理页面配置“商 家小票链接”后,商家小票链接会嵌入该 Iframe 框架内,同时,点金计划页面会与服务商交 互订单信息(如 3.4.2 所述),服务商获取订单信息并校验通过后,为用户展示对应的服务性

1) 打开点金计划管理页面
操作路径:【登录微信支付服务商平台 → 服务商功能 → 点金计划】。在“商家小票链接 配置”模块中,点击“添加商家小票链接”:

2) 按照页面操作指引添加一个链接

商家小票链接仅支持 https 协议,同时需通过 ICP 备案的验证,且应保证该链接线上可访 问。

内容即可。1、服务商维度配置商家小票链接

3) 下载验证文件,验证链接所有权 将从添加商家小票链接页面下载的验证文件放置在要填写的链接目录下,以证明对该链接的 所有权。放置完毕并确保该路径可访问后,填写链接并点击“提交”,微信支付后台会进行 验证文件的查验,查验通过后即提交成功。 注:将验证文件放置在所填链接的目录或根目录均可。
4) 使用“商家小票调试工具”进行调试 为了保证商家小票在点金计划页面展示的兼容性、完整性,平台还提供了便捷的商家小票调 试工具供服务商进行调试。服务商可通过商家小票调试工具,使用所选链接和真实订单号对 点金计划页面的数据交互流程、前端 JSAPI 的使用进行调试。具体调试内容请参考商家小票 开发指引

2、特约商户维度配置独立商家小票链接

部分特约商户(例如:医院、学校等类型)有特殊的域名要求,服务商可为这些特约商户配置
独立的商家小票链接。配置后,这些特约商户的点金计划页面将通过所特约商户维度的独立链
接进行订单数据交互。未配置特约商户独立商家小票链接的,将依然使用服务商维度的商家小
票链接。
特约商户维度独立的商家小票链接入口如下,具体步骤与上述服务商维度配置相同:

1.2 第二步:为特约商户打开“点金计划”开关

在点金计划管理页面的特约商户管理列表中选择特约商户,并在“点金计划”栏下打开开关即
可。直接打开“点金计划”开关后,该特约商户的点金计划页面将展示官方小票。

服务商也可通过“默认开通”按钮为全量特约商户开通点金计划。如下图所示,在特约商户管 理列表右上角有“默认开通点金计划”开关,打开后,只要特约商户产生 jsapi 支付,微信支 付将自动为其开通点金计划,无需服务商操作开通。

注意:
1)打开该开关后,平台将为发生了 jsapi 支付的特约商户自动开通点金计划,若特约商户未发 生 jsapi 支付,则不会为其自动打开点金计划;
2)若通过 API 或手动方式为某些特约商户关闭了点金计划开关,则平台不会再次为其自动开 通。

此外,微信支付侧提供“点金计划管理 API”,供服务商为特约商户批量开通点金计划,具体 请查看点金计划管理 API

1.3 第三步:为特约商户打开“商家小票”开关

打开“点金计划”开关后,服务商还需为特约商户打开商家小票的开关(若未配置商家小票链
接或打开点金计划开关,则无法打开商家小票开关)。

在特约商户管理列表中选择特约商户,在“商家小票”栏下打开开关即可。 同时,平台提供“商家小票管理 API”,供服务商为特约商户批量开通/关闭商家小票功能,具 体请查看商家小票管理 API

2.商家小票开发指引
2.1 商家小票链接数据交互(重要)

点金计划页面会通过如下流程与商家小票链接进行数据交互,以方便商家快速获取订单基础信
息,为用户展示服务性内容。

1) 通过商家小票链接获取用户订单信息:
点金计划页面打开时,页面上方的
iframe 框架会请求服务商填写的商家小票链接,会在链 接后附上:“特约商户号(sub_mch_id)”、“商户订单号(out_trade_no)”、

md5 校验码(check_code)”三个字段的信息,方便服务商快速定位到具体订单的同 时,也保证链接的可靠性。

a) 增加参数后的链接格式为: 服务商链接?sub_mch_id=特约商户号&out_trade_no=商户订单号&check_code=

b) 举例:
若服务商配置的链接为
https://www.qq.com,特约商户号为 1234567,商户订单号为ABCDEFG,则请求的链接为https://www.qq.com?sub_mch_id=1234567&out_trade_no=ABCDEFG&check_code = 39f0876dd58e4eb61b66250f69d02705

2) 服务商校验 check_code服务商获取到上述完整链接时,为了保证参数没有被篡改,需要做 MD5 校验。

a) 校验方式 通过链接上的“商户订单号”,到后台获取该订单对应的“微信订单号”,即transaction_id,并拼在原有链接后(需去除 check_code,即:服务商链 接?sub_mch_id=特约商户号&out_trade_no=商户订单号&transaction_id=),进行MD5 计算。

b) 举例
transaction_id abcdefg,则 MD5 值为:
String my_check_code = MD5(“https://www.qq.com?sub_mch_id=1234567&out_trade_no=ABCDEFG&tran saction_id=abcdefg”);

my_check_code 与最初链接参数中的 check_code 相等,说明该链接未被篡改,可

正常跳转到商家小票内容,否则服务商需展示错误提示页。3) 商家小票尺寸适配:

点金计划页面上方的商家小票 Iframe 框架默认尺寸为 640px*600px,会根据各手机型号 的屏幕宽高比自适应展示。服务商页面需兼容该尺寸,若 Iframe 框架高度不满足展示诉 求,可参考点金计划页面 JSAPI 的指引调整高度。

2.2 点金计划页面 JSAPI

为了提升用户体验,满足商家各类业务需求,点金计划页面提供了一系列 JSAPI,协助商家实 现以下功能:
1、按订单确认是否展示商家小票(onIframeReady 事件):已开通商家小票功能的特约商户, 服务商依然可以按照当前订单的情况决定是否展示商家小票(也可选择直接展示官方小票)。2、调整 Iframe 框架高度(onIframeReady 事件):供服务商调整商家小票区域的整体高度 (规则:以宽度 640px 为基准,商家小票高度最小 600px,最大 960px。若服务商通过 jsapi传入高度小于 600px,页面展示 600px;若传入高度超过 600px 但不超过 960px,按传入高 度展示;若传入高度大于 960px,页面仅展示 960px)。

3、外跳新页面(jumpOut 事件):支持从点金计划页面上方的商家小票区域,点击外跳到商 家的完整页面(此处不可模拟用户点击自动外跳,否则相关能力会被处罚)。点击外跳时将出 现弹窗,显示“即将打开商家的新页面“和商家简称,用户点击确定后实现外跳。

以下为具体的 jsapi 事件描述,每个事件的触发时机不同,请留意下文对每个事件的触发时机 说明:

2.2.1 onIframeReady 事件(重要)

所有订单必须响应 onIframeReady 事件,否则无法正常进行商家小票的展示。

通信方式:iframe postMessage 事件通知 数据格式:json 字符串 事件名称:onIframeReady
事件功能:

1)按订单确认是否展示商家小票

2)调整 Iframe 框架高度

触发时机:商家小票页面完全渲染完毕之后

事件参数:

参数

说明

类型

是否必填

action

事件名称:onIframeReady

String

displayStyle

需展示的页面,目前有两个值:1.展示商家小票 SHOW_CUSTOM_PAGE 2.展示官方小票 SHOW_OFFICIAL_PAGE

String

height

自定义高度,范围 600-960px(按宽度 640px 为基数进行转换); 若不传,则为默认高度 600px;若传入高度超过 600px 但不超过960px,按传入高度展示;若传入高度大于 960px,页面仅展示 960px。 若 displayStyle SHOW_OFFICIAL_PAGE,则传入 height 无效

Int

备注:
1) 展示商家小票时,建议在商家小票页面渲染完毕后再调用 JSAPI;
2) 从加载商家小票到响应 onIframeReady 事件之间的用时不可超过 3s,若超过 3s

  响应,为保证用户体验,平台会为用户展示如下图所示的超时页面和刷新按钮,用户
  可点击刷新按钮重新请求商家小票内容。

示例:
(
1)展示商家小票:

let mchData ={action:'onIframeReady',displayStyle:'SHOW_CUSTOM_PAGE'} let postData = JSON. stringify(mchData) parent.postMessage(postData,'https://payapp.weixin.qq.com')

(
2)展示官方小票:

let mchData ={action:'onIframeReady',displayStyle:'SHOW_OFFICIAL_PAGE'}

let postData = JSON. stringify(mchData)

parent.postMessage(postData,'https://payapp.weixin.qq.com')

(3)自定义高度:

let mchData

={action:'onIframeReady',displayStyle:'SHOW_CUSTOM_PAGE',height:900}

let postData = JSON. stringify(mchData)

parent.postMessage(postData,'https://payapp.weixin.qq.com')

注,由于各手机屏幕尺寸不同,为避免设置固定高度值带来的体验不一致问题,服务商可按如下换 算规则计算出通过 jsapi 传给点金计划父页面的高度值:
Step1:计算服务商页面当前高度
const customPageHeight = document.body.scrollHeight; // 单位 px Step2:换算传入点金计划页面的高度

传给父页面的高度(单位:px) = customPageHeight * (640 / 子页面真实宽度)
const height = customPageHeight * (640 / Math.round(document.documentElement.getBoundingClientRect().width));
其中:传给点金计划页面的 height 值需遵循文档规范,请勿超过限定范围:[600px, 960px],即600 <= height (单位 px)<= 960;

2.2.2 jumpOut 事件

通信方式:iframe postMessage 事件通知 数据格式:json 字符串

事件名称:jumpOut事件功能:若商家业务流程需要从商家小票区域外跳到商家新页面,可通过该 JSAPI 传递 外跳 URL,实现外跳。。触发时机:商家页面有外跳需求,且用户主动点击时(此处不可模拟用户点击自动外跳,否 则相关能力会被处罚)
事件参数:

示例:

let mchData ={action:'jumpOut', jumpOutUrl:'https://www.qq.com'} let postData = JSON. stringify(mchData) parent.postMessage(postData,'https://payapp.weixin.qq.com')

2.3 点金计划页面 JSSDK(重要)

为了保证支付后生态环境的健康发展,平台会对嵌入点金计划页面的商家小票链接(含跳转链 接)进行记录,同时会对商家小票页面内容进行安全监测。 因此,所有嵌入点金计划页面的商家小票链接均需在 HTML header 中引入:
<script type="text/javascript" charset="UTF-8" src="https://wx.gtimg.com/pay_h5/goldplan/js/jgoldplan-1.0.0.js"></script>若未引用,平台会根据《点金计划须知和承诺函》中的相关规定对服务商进行功能处罚。

参数

说明

类型

是否必填

action

事件名称:jumpOut

String

jumpOutUrl

外跳链接

String

2.4 注意事项

1) 为了保证商家小票区域美观性,给用户更好的页面体验,商家小票设计规范建议参考 《点金计划商家小票模块设计规范建议》;
2) 请尽量降低页面请求资源包大小,提升链接打开速度,保障用户体验;
3) 微信支付将会实时对商家小票内容进行安全检测,商家小票仅可放置例如“取餐 码”、“用户评价”、“停车剩余时长”等围绕用户进行服务的内容,请勿出现涉政、黄、 赌、毒等违规的内容和行为;且不得出现模拟用户点击、自动触发跳转的行为。一经出现, 平台会关闭其“商家小票”功能,并会进一步联动处罚。

3.同业过滤标签设置(可选)

点金计划还为商家提供了过滤同业广告的能力(即同业过滤标签设置),服务商只需在点金计 划管理页面,选中需设置的特约商户,并点击操作栏的“修改标签”,在标签配置页面选择需 过滤的行业标签并点击确认即可。 注:特约商户默认无同业过滤标签,且每个商户最多只能设置 3 个标签。其中,未开通点金计 划的特约商户不可设置。

4.关闭广告展示(可选)

为了满足某些特约商户不展示广告的诉求,点金计划还提供了关闭广告的能力,服务商只需在 点金计划管理页面,选中需设置的特约商户,在“广告展示”栏下关闭开关即可。 同时,平台提供“关闭广告展示 API”,供服务商为特约商户批量关闭广告展示功能,具体请 查看关闭广告展示 API。若需重新打开广告展示,也可通过“开通广告展示 API“再次为特约 商户批量操作,且