名词解释
1. 口碑码:分为门店码和桌码,集成阶段建议使用测试门店,测试门店生成办法:[url]https://openclub.alipay.com/read.php?tid=4013[/url]。
正式门店的口碑码是由口碑服务商生成的,正式门店的门店码可以通过登录【口碑商家后台】,在左侧导航栏找到“我的门店”,列表中对应门店左侧即是正式门店码。
测试门店码和测试桌码生成办法:
桌码——
alipays://platformapi/startapp?appId=20000238&target=merchant&shopId=2016062900077000000016003316&tableNo=A04&codeId=9999999&bizScene=KOUBEI_TABLE_CODEC&chInfo=dfqwegq3&j=detail_service_card
shopId:换成测试店铺ID,tableNo换成门店回传过的桌码,其他不用换,就可以直接测试了
2. 服务card:如下图中红色框
3. 插件区,又称服务位:如下图中红色框
4.“码上付”,又称“秒付”
表现层
注:该用户流程为码上付服务的标准主流程,ISV需按照此标准流程进行开发,否则服务验收时将会被驳回。
附:【码上付交互视觉规范】
对接准备(以测试门店和测试服务为例)
1、 应用(如果还没有自己的应用,可见【创建应用】:[url]https://openclub.alipay.com/read.php?tid=1606[/url])
(1)如果是商户自己开发,需要添加口碑码战略、当面付功能,当面付需要签约,有BD请联系BD签约,如若没有BD,并且不清楚如何签约,可参考[url]https://openclub.alipay.com/read.php?tid=276[/url]
(2)如果是ISV代商户开发,需要ISV在自己的应用添加口碑码战略、第三方应用授权功能,商户签约当面付产品,商户第三方应用授权给ISV,建议ISV在回流数据的时候传入APP_auth_token参数,创建支付订单的时候必须传递APP_auth_token参数
注:我们强烈建议回流数据和APPID和创建支付订单的APPID是同一个,如若不是,请务必保证回流数据的APPID和创建支付订单的APPID同属一个PID
2、 测试服务(集成阶段建议使用测试服务,可参考【测试服务创建办法】:[url]https://openclub.alipay.com/read.php?tid=3988[/url])
3、 测试门店(集成阶段建议使用测试门店,可参考【测试门店创建办法】:[url]https://openclub.alipay.com/read.php?tid=4013[/url]) ,测试门店默认有显示服务card的能力,正式门店需要扫码点菜验收通过后才露出显示服务card的能力
产品交互流程
具体步骤:
在口碑与ISV的交互流程中主要包括如下3步:①通知回流,②ISV订单回流,③跳转ISV支付地址
① 通知回流
1.当用户扫码启动店铺门店页时,口碑将通过ISV配置的网关向ISV发送通知(URL),并在通知(URL)中携带各种参数,ISV可从通(URL)中将各参数的值解析出来,用于下步的订单回流。
重点注意事项:ISV成功接收到通知后返回success,若无返回则口碑会重试几次。这里放入通知为异步通知,通知规则和支付的异步通知一致,【可参考】。
2.通知地址:口碑向ISV发送通知的地址使用的是ISV配置应用时所使用的应用网关地址,如下图中红框的部分;如需了解如何配置应用网关,可查看【应该网关配置说明】:[url]http://docs.open.alipay.com/200/105310/#s2[/url]。
3.口碑向ISV发送的通知(URL)举例
应用网关?notify_type=koubei_open_data_sync_notify&charset=UTF-8&biz_content={"merchant_pid":"2088201919503363","shop_id":"2016110400077000000003446012","user_id":"2088102151186045","table_num":"A08”}¬ify_time=2017-04-27 15:33:19&sign=***&app_id=2016122201272580&version=1.0&sign_type=RSA¬ify_id=9b5cceb48f83047ecc8064aa990fdf9l0m
4.ISV需要做的:
②ISV订单回流
在口碑向ISV发送通知回流信息后,ISV需使用订单回流接口向口碑传递回流信息。
代码demo:
1.13状态
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", AlipayConfig.app_id,AlipayConfig.merchant_private_key,"json","GBK",AlipayConfig.alipay_public_key,"RSA2"); AlipayOfflineProviderUseractionRecordRequest request = new AlipayOfflineProviderUseractionRecordRequest(); //request.putOtherTextParam("app_auth_token","201801BB6b27c190986b4dac9e85e66d5aec7X35");第三方应用授权 request.setBizContent("{" + //集成阶段传递此参数,传递之后,在支付宝钱包-口碑tab-我-我的订单-服务订单中显示一条数据,正式环境默认有显示服务订单的能力,不用传递此参数 "\"is_test_user\":\"1\","+ "\"source\":\"alipay.com\"," + "\"action_type\":\"order_dishes\"," + "\"industry\":\"REPAST\"," + "\"order_type\":\"online_pay\"," +//码上付场景此参数必填,传递online_pay参数标志这是一笔码上付的数据 "\"user_id\":\"20887129xxxxxxx\","+//user_id以2088开头,建议传递,此参数会影响服务card的实时刷新,可通过用户信息授权接口获取 "\"date_time\":\"2018-02-11 10:16:30\"," + "\"action_detail\":{"+ "\"totalPrice\":\"33\","+ //总价,这里需要注意的是单位分 "\"discountPrice\":\"33\","+ //优惠金额,这里需要注意的是单位分 "\"realPrice\":\"33\","+ //实际支付,这里需要注意的是单位分 //从第三方平台进入开发者应用,后产生的数据,传入第三方平台域名, //比如当前数据是支付宝扫码后产生,传入支付宝域名alipay.com //是在微信打开后产生的数据,传入微信域名weixin.qq.com //是在口碑打开后产生的数据,传入口碑域名koubei.com //如果数据不是从第三方平台进入后产生的数据,设置自己的域名即可 //字段内容不做强制校验。 "\"source\":\"alipay.com\","+ "\"status\":\"13\","+ //13商家确认,用户待支付 //外部订单号,这里需要注意的是,从用户下单,商家确认,待支付,支付完成,是一笔订单 "\"outOrderId\":\"20180211094030333\","+ "\"tableCode\":\"A09\","+ //桌号,此参数必填,该参数会影响该餐台的card更新 "\"people\":\"2\","+//消费人数,建议传递 //detailUrl参数必传,直接影响到支付宝钱包-口碑tab-我-我的订单-服务订单,点击一条数据后跳转的链接 //传入要求参考文档要求 "\"detailUrl\":\"http://47.100.40.54:8080/Test/index.jsp\","+ //菜品列表 //goodsId菜品ID,自定义 //goodsName 菜品名称,自定义 //price 价格,单位为分,自定义 //num 点菜数量(int),自定义 "\"dish\":[{\"goodsId\":\"216137\",\"price\":2,\"num\":1,\"goodsName\":\"酱爆茄子\"}],"+//菜品列表 "\"statusDesc\":\"待支付\","+//状态文案说明,会影响card左上角的文案。请准确描述当前的状态 //行动点对象列表,每次更新全量覆盖,此参数会直接影响服务card上面的按钮显示。请准确描述当前的状态 //String name ; 行动名称(比如,去买单、加菜,查看详情,再来一单) //String actionUrl 跳转URL,建议ISV自行对该url进行加签验签,以避免被恶意程序拦截篡改 //String type URL类型(官方常量 addDish(加菜) pay (去买单),官方会根据类型做业务逻辑,如果不在官方说明,请设置为空) "\"actionUrlList\":[{\"name\":\"查看详情\",\"actionUrl\":\"http://47.100.40.54:8080/Test/index.jsp\",\"type\":\"\"}," + "{\"name\":\"去支付\",\"actionUrl\":\"http://47.100.40.54:8080/Test/index.jsp\",\"type\":\"pay\"}],"+ //与当前订单有关系的用户,传入json数组 //如果不是支付宝用户不需要传入,如果order_channel是alipay,强制校验,必须要传入 //String userId (支付宝用户ID) //String type (用户ID行为类型),type 可以选择设置字符串value:pay,pushOrder,normal //type各value值含义说明: //pay:支付者 //pushOrder:下单的用户 //normal:普通用户,没有做特殊说明的都是普通用户 "\"realtionUserList\":[{\"userId\":\"208871296973xxxx\",\"type\":\"pay\"}]"+ "}," + //店铺关联关系。标记当前接口涉及到的店铺信息,同时如果传入的数据在口碑不存在,口碑会建立一条shop_id+outer_id+type的关联数据 //传递之后,建议不要再修改此参数 "\"outer_shop_do\":{"+ "\"shop_id\":\"2017080300077xxxxxxxxxxx\","+//门店id "\"outer_id\":\"123456\","+//ISV系统中与口碑店铺shop_id关联的ISV店铺主键 "\"type\":\"http://47.100.40.54:8080/Test/index.jsp\""+//建议直接传入ISV的域名 "},"+ "\"entity\":\"user\"," + "\"action_outer_id\":\"20180126145930333\"," +//每次请求的唯一id,需开发者自行保证此参数值每次请求的唯一性 "\"order_channel\":\"isv\"" +//该字段建议填写。值定义:alipay、weixin、other、isv"}"); AlipayOfflineProviderUseractionRecordResponse response; try { response = alipayClient.execute(request); if (response.isSuccess()) { System.out.println("调用成功" + response.getBody()); } else { System.out.println("调用失败" + response.getBody()); } } catch (AlipayApiException e) { // TODO Auto-generated catch block e.printStackTrace(); }
2.14状态
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", AlipayConfig.app_id,AlipayConfig.merchant_private_key,"json","GBK",AlipayConfig.alipay_public_key,"RSA2"); AlipayOfflineProviderUseractionRecordRequest request = new AlipayOfflineProviderUseractionRecordRequest(); //request.putOtherTextParam("app_auth_token","201801BB6b27c190986b4dac9e85e66d5aec7X35");第三方应用授权 request.setBizContent("{" + //集成阶段传递此参数,传递之后,在支付宝钱包-口碑tab-我-我的订单-服务订单中显示一条数据,正式环境默认有显示服务订单的能力,不用传递此参数 "\"is_test_user\":\"1\","+ "\"source\":\"alipay.com\"," + "\"action_type\":\"order_dishes\"," + "\"industry\":\"REPAST\"," + "\"order_type\":\"online_pay\"," +//码上付场景此参数必填,传递online_pay参数标志这是一笔码上付的数据 "\"user_id\":\"208871296973xxxx\","+//user_id以2088开头,建议传递,此参数会影响服务card的实时刷新,可通过用户信息授权接口获取 "\"date_time\":\"2018-01-26 14:44:30\"," + "\"action_detail\":{"+ "\"totalPrice\":\"33\","+ //总价,这里需要注意的是单位分 "\"discountPrice\":\"33\","+ //优惠金额,这里需要注意的是单位分 "\"realPrice\":\"33\","+ //实际支付,这里需要注意的是单位分 //从第三方平台进入开发者应用,后产生的数据,传入第三方平台域名, //比如当前数据是支付宝扫码后产生,传入支付宝域名alipay.com //是在微信打开后产生的数据,传入微信域名weixin.qq.com //是在口碑打开后产生的数据,传入口碑域名koubei.com //如果数据不是从第三方平台进入后产生的数据,设置自己的域名即可 //字段内容不做强制校验。 "\"source\":\"alipay.com\","+ "\"status\":\"14\","+ //13商家确认,用户待支付 //下面三个参数在14状态下必传 "\"payTime\":\"\","+ //注意,这里是精确到毫秒,此参数传递错误,会影响清台后的服务card正常显示 "\"channel\":\"alipay\","+ "\"payOrderNo\":\"2018012321001004350510117761\","+ //外部订单号,这里需要注意的是,从用户下单,商家确认,待支付,支付完成,是一笔订单 "\"outOrderId\":\"20180126145930222\","+ "\"tableCode\":\"A05\","+ //桌号,此参数必填,该参数会影响该餐台的card更新 "\"people\":\"2\","+//消费人数,建议传递 //detailUrl参数必传,直接影响到支付宝钱包-口碑tab-我-我的订单-服务订单,点击一条数据后跳转的链接 //传入要求参考文档要求 "\"detailUrl\":\"http://17675wt546.iok.la:29682/pc/notify_url.jsp\","+ //菜品列表 //goodsId菜品ID,自定义 //goodsName 菜品名称,自定义 //price 价格,单位为分,自定义 //num 点菜数量(int),自定义 "\"dish\":[{\"goodsId\":\"216137\",\"price\":2,\"num\":1,\"goodsName\":\"酱爆茄子\"}],"+//菜品列表 "\"statusDesc\":\"已支付\","+//状态文案说明,会影响card左上角的文案。请准确描述当前的状态 //代表是否清桌,默认0。1:清桌,代表桌位可以被他人使用。0:占用,代表座位正在被人使用(比如点菜中、订单没有完结,都认为是被占用中,其他人员无法再次下单) //对表现层的影响是,如果传了1,则只有支付用户和下单用户在传递的payTime参数内的半小时见realtionUserList参数)能看到card,其他用户为新的card。 //如果传了0,则所有用户扫桌码都会看到当前card。 "\"hasClosed\":\"1\","+ //行动点对象列表,每次更新全量覆盖,此参数会直接影响服务card上面的按钮显示。请准确描述当前的状态 //String name ; 行动名称(比如,去买单、加菜,查看详情,再来一单) //String actionUrl 跳转URL,建议ISV自行对该url进行加签验签,以避免被恶意程序拦截篡改 //String type URL类型(官方常量 addDish(加菜) pay (去买单),官方会根据类型做业务逻辑,如果不在官方说明,请设置为空) "\"actionUrlList\":[{\"name\":\"查看详情\",\"actionUrl\":\"http://www.ieasy360.com\",\"type\":\"pay\"}],"+ //与当前订单有关系的用户,传入json数组 //如果不是支付宝用户不需要传入,如果order_channel是alipay,强制校验,必须要传入 //String userId (支付宝用户ID) //String type (用户ID行为类型),type 可以选择设置字符串value:pay,pushOrder,normal //type各value值含义说明: //pay:支付者 //pushOrder:下单的用户 //normal:普通用户,没有做特殊说明的都是普通用户 "\"realtionUserList\":[{\"userId\":\"208871296973xxxx\",\"type\":\"pay\"}]"+ "}," + //店铺关联关系。标记当前接口涉及到的店铺信息,同时如果传入的数据在口碑不存在,口碑会建立一条shop_id+outer_id+type的关联数据 //传递之后,建议不要再修改此参数 "\"outer_shop_do\":{"+ "\"shop_id\":\"20170803000770000xxxxxxxxxx\","+//门店id "\"outer_id\":\"123456\","+//ISV系统中与口碑店铺shop_id关联的ISV店铺主键 "\"type\":\"http://17675wt546.iok.la:29682/pc/notify_url.jsp\""+//建议直接传入ISV的域名 "},"+ "\"entity\":\"user\"," + "\"action_outer_id\":\"20180126145430111\"," +//每次请求的唯一id,需开发者自行保证此参数值每次请求的唯一性 "\"order_channel\":\"isv\"" +//该字段建议填写。值定义:alipay、weixin、other、isv "}"); AlipayOfflineProviderUseractionRecordResponse response; try { response = alipayClient.execute(request); if (response.isSuccess()) { System.out.println("调用成功" + response.getBody()); } else { System.out.println("调用失败" + response.getBody()); } } catch (AlipayApiException e) { // TODO Auto-generated catch block e.printStackTrace(); }
③跳转ISV支付地址
1.当ISV完成订单回流后,服务card会即时刷新,用户点击底部插件区“去买单”按钮时,就会跳转到ISV的支付地址,该地址即ISV创建码上付服务时配置的用户访问地址(如下图所示)加上相关业务参数;;如需了解如何配置用户访问地址,可查看【创建服务填写说明】:[url]https://openclub.alipay.com/read.php?tid=3988[/url]。