开通芝麻 GO 流程图

商家从自己的 App 或者小程序拉起芝麻 GO 官方小程序提供的渲染页进行签约流程发起，渲染页展示开通的业务信息，进行芝麻 GO 产品的签约，后跳转到通行结果页，用户进行签约确认。

第一步：获取用户授权

商家可通过 my.getAuthCode 获取 user_id（用户支付宝 ID）。

说明：

若只是获取用户的支付宝 user_id，可以不经过用户的授权确认，直接静默获取。

若还需获取用户其它支付宝信息，如手机号等，就需要弹出用户授权框，用户确认后才可获取.

从用户转化来讲，建议尽量只获取支付宝 user_id 即可，用 user_id 来绑定用户和商家会员之间的关系。

第二步：签约预创单

商家拉起签约前需要调用 zhima.credit.pe.zmgo.preorder.create（芝麻GO签约预创单接口）提前提前传入请求号、业务时间、关键配置参数，返回预创单号。在正式拉起签约页时带入预创单号，关联到提前传入的配置。

预创单作用：

提前传入签约阶段参数，简化拉起签约页参数和链接长度并支持传入特殊场景所需的业务参数，例如在运营商场景下需要传入的风控参数。

后续依赖 zhima.credit.pe.zmgo.preorder.create（芝麻GO签约预创单接口）传入动态模板配置的 template_id，实现模板配置，若无预创单则不支持。

参数说明

其中本场景需要传入风控参数，规则如下：

由extend_params#order_feature参数透传，格式为：key@@@value|||key@@@value，可查看下表：

参数	类型	是否必填	最大长度	描述	示例值
service_telphone	String	是	11	套餐手机号	151xx0588xx说明：若获取不到，请点击文档右下角 > 在线咨询，咨询技术支持。
user_name	String	是	16	机主姓名	张三说明：若获取不到，请点击文档右下角 > 在线咨询，咨询技术支持。
net_age	String	是	64	网龄	12，手机号开通距今月份数，新卡0。说明：若获取不到，请点击文档右下角 > 在线咨询，咨询技术支持。
branch_company	String	否	64	分公司	有则传
source	String	是	64	进件渠道：社会厅、直营厅、APP等，若获取不到请反馈	-
service_accept_time	String	否	64	受理时间	-
operator_id	String	否	64	进件员工ID	-
total_bonus	String	是	64	最高优惠金额	-
step_num	String	是	64	合约总期数	-
busi_type	String	是	64	套餐类型：单产品/套餐融合	-
busi_level	String	是	64	套餐每月保底金额	若获取不到请反馈
busi_name	String	否	64	套餐名称	有则传
pre_busi_level	String	否	64	原套餐每月保底金额。	若是新卡或获取不到用户当前使用套餐金额，可不传。
merchant_id	String	是	64	门店ID	-
merchant_name	String	是	64	门店名称	-
merchant_addr	String	是	64	门店地址	-

商家需要记录下返回的预创单号 preorder_no 和业务身份 biz_type，在拉起签约阶段传入。响应参数列表：

参数	类型	是否必填	最大长度	描述	示例值
preorder_no	String	需要在拉起签约页阶段传入此参数	64	芝麻GO预创建单号	ZMGO_ASO2019071000020903940000062019
partner_id	String	必填	16	商户ID	2088990000000000
biz_type	String	需要在拉起签约页阶段传入此参数	64	业务类型	bizflag

第三步：拉起签约页

构造签约的 URL

商家 App 端传入必要参数给商家服务端，服务端调用 zhima.credit.pe.zmgo.sign.apply（芝麻GO页面签约接口）进行参数的加签并返回前端唤起支付宝小程序的需要的 URL 参数。

请求示例

**说明：**建议使用 JSONObject 构造 bizContent。

// app_id,密钥等在接入流程中完成，可从open.alipay.com获取
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
ZhimaCreditPeZmgoSignApplyRequest request = new ZhimaCreditPeZmgoSignApplyRequest();
// 回跳地址，签约成功回跳
request.setReturnUrl("http://www.alipay.com/receive.html");
request.setBizContent("{" +
"\"partner_id\":\"2088102146225135\"," +
"\"template_id\":\"2018053100073208416400000002\"," +
"\"preorder_no\":\"ZMGO_ASO2021012121312312312312\"," +
"\"biz_type\":\"bizflag\"" +
"}");
ZhimaCreditPeZmgoSignApplyResponse response = alipayClient.pageExecute(request,"GET");
// 获取oOpenAPI调用URL，主要获取后面的参数
String openUrl=response.getBody();

注意：构造 request 的时候不能设置 notifyUrl，否则后续签约流程会报错，暂时不支持自定义 notifyUrl。

其中 biz_content 中对应参数：

参数名	描述	是否必填	举例
partner_id	商户 ID	是	2088301614697946
template_id	模板 ID	是	2019071000020903940000062019
out_request_no	外部请求号	调用预创单不用传，不走预创单必传	8077735255938032
preorder_no	预创单号	调用预创单后，此参数必传，从预创单返回值中取；不进行预创单则不传。	ZMGO_ASO2021012121312312312312
biz_type	业务标识	调用预创单后，此参数必传，从预创单返回值中取	bizflag

响应示例

https://openapi.alipay.com/gateway.do?alipay_sdk=alipay-sdk-java-3.4.107.ALL&app_id=2018110762025907&biz_content={"seller_id"%3A"2088102146225135"%2C"template_id"%3A"2018053100073208416400000002"%2C"out_request_no"%3A"8077735255938032"%2C"channel"%3A"channel_external"++}&charset=GBK&format=json&method=alipay.pcredit.huabei.auth.sign.apply&return_url=http%3A%2F%2Fwww.alipay.com%2Freceive.html&sign=C6N8kXqHSG6AOU1CwPrdqojH4pK1U0TCDClTPTNQ5EN9pO%2BRz3FGSB8E%2FWrT8Zi14zGln0n1yv4TVlxPqycjQA8%2BffvLLSs4Y7l5hFLg5cdNyZ0xEt4Rw5yHqZyXQ0VCgVdxqdOSHIYfoNMkvEVA%2BXO1HalA4Rkf3ibgCMpK6W8gw4KzZeiYR7RazGeKJZ5N2mvP7AnzIHYShmf%2FABlrSv3wLXV%2FcVgriKnOWtOeFmgpS32B0RFdxVD7YEiE1mGlpPxTrjhzgVTXOF0z6LzAalEcmmb10W2OVHZyDzS8bwqgCMjubCnS%2FK%2Bsw%2BMDgS%2Fkt8wdeLRe%2BVZA69GTjNbaqg%3D%3D&sign_type=RSA2&timestamp=2019-08-03+13%3A35%3A30&version=1.0

**注意：**商家需将 http://openapi.alipay.com/gateway.do? 后面的所有参数作为加签字符串。

拉起签约页

商家 App 拉起签约页

如果是商家 App 拉起签约页，可构造 scheme 拉起支付宝签约页面：

判断是否安装支付宝客户端首先判断客户端是否安装有支付宝客户端，有则打开进入签约页面。判断有无方法。

iOS 平台：判断 scheme: alipays://是否能打开。

Android 平台：判断 package name com.eg.android.AlipayGphone 是否存在。

构造 scheme 链接上文 构造签约的 URL > 响应示例 中，gateway.do?后的参数再加上前缀 alipays://platformapi/startapp?appId=2019062465587961&page=pages/hz-enjoy/pass/index?extraData=。注意：此处 extraData 前面部分全部为固定值，不需要修改。

// 原始参数字符串
const signParams = 'alipay-sdk......';//构造签约URL中的字符串A
// encode 参数这里需要在外边encode两次
const sign = encodeURIComponent(encodeURIComponent(JSON.stringify({signParams: encodeURIComponent(signParams)})))
// 小程序跳转URL
const url = 'alipays://platformapi/startapp?appId=2019062465587961&page=pages/hz-enjoy/pass/index?extraData='+sign

完整 schema 示例

alipays://platformapi/startapp?appId=2019062465587961&page=pages/hz-enjoy/pass/index?extraData=%257B%2522signParams%2522%253A%2522alipay_sdk%25253Dalipay-easysdk-java%252526app_id%25253D2021000119688827%252526biz_content%25253D%2525257B%25252522preorder_no%25252522%2525253A%25252522ZMGO_ASO000000000000000000000000%25252522%2525252C%25252522partner_id%25252522%2525253A%252525222088301614697946%25252522%2525252C%25252522biz_type%25252522%2525253A%25252522bizflag%25252522%2525252C%25252522template_id%25252522%2525253A%2525252220200312000209030100008736478%25252522%2525257D%252526charset%25253DGBK%252526format%25253Djson%252526method%25253Dzhima.credit.pe.zmgo.sign.apply%252526notify_url%25253Dhttp%2525253A%2525252F%2525252F11.163.133.214%2525253A7001%2525252Fcallback%2525252Fpp3-PG.MID.redbagsign-alipay.zhimago-notification%2525252F0-0%2525252F2201250736354%2525252F%252526return_url%25253Dhttps%2525253A%2525252F%2525252Fwww.alipay.com%2525252F%252526sign%25253DIhKFj0iu1vzDG8C8%2525252F3T%2525252FOgEMBaSeDwgD7W%2525252F5es6j0o0rlAxHhnRuNwNmSzU6iVv5bpusuyuUYRwCrdYsIE7OWkEl4tURsyZzOdMYGnYcYvHEAkncOc8hWnt1BRjnPI7mPB6Z8pUIEO4G47d5h7cneiflSvG4iOc3gLTeLXpJboPgBRNOjATZBn%2525252BjvOOL3m%2525252FmaQAIKyHiZqp3GwNptzISBOoBqA4asYMj6LNkQ8ZJFAgqUAKUWfOxdYQOncdTiHS1v%2525252Ft5qbEOH22PLga4zCqWqgPE2Kj2pxwoznTGnpq640Sbuayq%2525252B5e%2525252FiFGskTsh8GHqZ9ysB6PB%2525252Fq%2525252BqxywhHZjReg%2525253D%2525253D%252526sign_type%25253DRSA2%252526timestamp%25253D2021-03-07%25252B14%2525253A07%2525253A21%252526version%25253D1.0%2522%257D

增加签约失败的跳转链接

scheme 链接还可增加 failedUrl参数，签约失败或者取消签约会跳转到对应的链接上。

构造链接方式如下：

failedUrl 值可选项：

popWindow 失败情况下只关闭当前小程序（不能与下文的 usePopWindow 共存）。

http 链接 或者 App 的 scheme 失败情况下跳转对应链接，但是不关闭当前小程序。

// 签约失败或者取消签约需要跳转到其它的链接地址 （非上文的return_url）
// 需要新增一个 failedUrl 参数
// 原始参数字符串
const signParams = 'alipay-sdk......'
// encode 参数
const sign = encodeURIComponent(JSON.stringify({failedUrl:encodeURIComponent('https://xx.yy.com'), signParams: encodeURIComponent(signParams)}))
// 小程序跳转URL
const url = 'alipays://platformapi/startapp?appId=2019062465587961&page=pages/hz-enjoy/pass/index?extraData='+sign

签约成功后回跳商户 App 的唤端 URL 格式说明

唤端 URL 即 returnUrl/return_url，就像给服务器资源分配一个 URL，以便外部去访问它一样，商家/服务商同样也可以给手机 App 分配一个特殊格式的 URL，用来访问这个 App 或者这个 App 中的某个功能，从而实现通信。

唤端 URL 格式：[scheme:][//host:port][path][?query][#fragment]

以 https://www.taobao.com 为例，scheme 为 https。

App 得有一个标识，以便外部可以定位到它，它就是 URL 的 Scheme 部分。唤端淘宝 App 的URL链接：taobao://www.taobao.com。

因此要唤端模式接入的商家需要根据自己的 App 应用标识替换正常 URL 链接中的 scheme 部分。

说明：签约成功后如需回跳商家 App 指定页面，开发者需将 returnUrl 替换为对应的内容。

消息通知

消息订阅注意事项

消息通知说明详情，可查看 From 蚂蚁消息通知。

若商家/服务商网络环境比较复杂，例如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。

该消息接口需商家进行订阅消息。

第一步：验签

商家/服务商可使用支付宝 SDK 根据数据验签指引，使用应用密钥信息验证 异步通知消息 来源是否为支付宝。

第二步：反馈消息接收结果

收到异步通知并 通过验签 后，商家/服务商需返回 success 表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其它值，表示消息获取失败，支付宝会根据投递重试策略重新发送消息到应用网关地址。

**说明：**在接收异步进行验签，如果验签成功输出 success，验签失败返回 fail，重新接收异步进行处理。

响应值	描述	是否重试
fail	消息获取失败	重试
success	消息获取成功	不重试

成功开通通知

用户开通芝麻 GO 成功后，支付宝将通过 zhima.credit.pe.zmgo.sign.notify（芝麻GO业务签约变更商户通知接口）推送签约通知至商家应用网关地址。

消息通知示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"zmgo_opt_no":"ZMGO_ORD2021012910020606010000042037","agreement_id":"ZMGO_AGR2021012910020604010000000001","sign_time":"2021-01-29 11:35:59","out_request_no":"63c0efbf3c62cf03ede783257ed66de8","freeze_amount":"100.00","alipay_user_id":"2088101117955611","template_id":"2020122900020903940000948530","partner_id":"2088101117755711","trans_status":"Y","biz_type":"EASY_MEMBER","sign_aisle_data":"API","start_time":"2021-02-01 11:35:57","exp_invalid_time":"2021-02-01 11:35:57","product_version":"zhimaGoV2","exemption_end_time":"2021-04-16 00:01:13","type":"NORMAL","withhold_plan_no":"ZMGO_WHD2021010910020603000000006002","original_price":"5.00","actual_price":"1.00","planned_trigger_time":"2021-04-14 00:01:13","time_out_time":"2021-05-01 00:01:13","total_periods":"6","agreement_status":"Y","agreement_desc":"星巴克免费券购物卡","cycle_withhold":"N"
}
&msg_method=zhima.credit.pe.zmgo.sign.notify&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

通知参数说明

注意：

消息属性 actual_price 在此场景下无实际意义。

商家需保存 agreement_id，后续的系统交互都以 agreement_id 识别用户身份

type=CYCLE_FLEX_WITHHOLD 可以判断是否为周期灵活扣玩法。

商家发起的结算申请时间段为 planned_trigger_time ～ time_out_time。无法提前发起，也不能超过这个时间。

actual_price 为发起的实扣金额。

商家发起周期灵活扣扣款申请时，需要传入 withhold_plan_no，这个字段唯一定位到芝麻 GO 首期扣款的扣款计划记录。

具体消息属性可查看 zhima.credit.pe.zmgo.sign.notify（芝麻GO业务签约变更商户通知接口）文档。

跳转芝麻 GO 管理页

跳转芝麻 GO 管理页链接示例：

alipays://platformapi/startapp?appId=2019062465587961&page=pages%2Fhz-enjoy%2FpassHome%2Findex%3FextraData%3D%7B%22appId%22%3A%22APP_ID%22%2C%22templateId%22%3A%22TEMPLATE_ID%22%2C%22partnerId%22%3A%22PARTNER_ID%22%2C%22agreementNo%22%3A%22AGREEMENT_NO%22%7D

说明：商家需将字符串中 APP_ID、TEMPLATE_ID、PARTNER_ID、AGREEMENT_NO 替换为自己的数据。

开通芝麻 GO

开通芝麻 GO 流程图#

第一步：获取用户授权#

第二步：签约预创单#

参数说明#

第三步：拉起签约页#

构造签约的 URL#

请求示例#

响应示例#

拉起签约页#

商家 App 拉起签约页#

完整 schema 示例#

增加签约失败的跳转链接#

签约成功后回跳商户 App 的唤端 URL 格式说明#

消息通知#

消息订阅注意事项#

第一步：验签#

第二步：反馈消息接收结果#

成功开通通知#

消息通知示例#

通知参数说明#

跳转芝麻 GO 管理页#