开通流程图

**说明：**商家可在自有 App、小程序唤起支付宝官方提供的渲染页进行签约流程。渲染页将展示开通的业务信息，用户点击按钮并通过授权验证，进行签约确认。用户签约成功后支付宝将发送异步消息通知商家。

第一步：获取用户授权

商家可通过用户授权获取 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，实现模板配置，若无预创单则不支持。

参数说明

入参详情可查看 zhima.credit.pe.zmgo.preorder.create（芝麻GO签约预创单接口）文档。

商家需要保存接口返回的 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。

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.setBizContent("{" +
"  \"partner_id\":\"2088102146225135\"," +
"  \"template_id\":\"2018053100073208416400000002\"," +
"  \"out_request_no\":\"8077735255938032\"," +
"  \"timeout_express\":\"90m\"," +
"  \"freeze_amount\":3.00," +
"  \"alipay_user_id\":\"2088982948537460\"," +
"  \"preorder_no\":\"ZMGO_ASO980000000000000000000000\"," +
"  \"extend_params\":{" +
"    \"isv_pid\":\"2088990000000000\"," +
"    \"scene\":\"TAOBAO\"" +
"  }" +
"}");
ZhimaCreditPeZmgoSignApplyResponse response = alipayClient.pageExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

其中 biz_content 中对应参数：

参数名	是否必填	参数描述	举例
partner_id	是	商家 ID，2088开头的商家唯一标识	2088301614697946
template_id	是	模板 ID，模板配置成功后获取	2019071000020903940000062019
out_request_no	特殊可选	外部请求号，调用预创单不用传，不走预创单必传	8077735255938032
preorder_no	特殊可选	预创单号，调用预创单后，此参数必传，从预创单返回值中取；不进行预创单则不传。	ZMGO_ASO2021012121312312312312
biz_type	特殊可选	业务标识，调用预创单后，此参数必传，从预创单返回值中取	bizflag

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

响应示例

https://openapi.alipay.com/gateway.do?alipay_sdk=alipay-sdk-java-3.4.107.ALL&app_id=2018110762025907&biz_content=%7B%22partner_id%22%3A%222088102146225135%22%2C%22template_id%22%3A%222018053100073208416400000002%22%2C%22out_request_no%22%3A%228077735255938032%22%7D&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? 后面的所有参数作为加签字符串。

拉起签约页

支付宝小程序拉起签约页

如果是商家支付宝小程序拉起签约页，需通过调用 my.navigateToMiniProgram 跳转至官方小程序签约页。使用案例如下，按照以下示例直接进行对接即可：

// 原始参数字符串
const signParams = 'alipay-sdk......';//构造签约的 URL 中的字符串 A
// encode 这里外边只用encode一次
const extraData = encodeURIComponent(JSON.stringify({signParams: encodeURIComponent(signParams)}));
my.navigateToMiniProgram({
  appId: '2019062465587961',// 固定值，代表芝麻GO官方小程序
  path: 'pages/hz-enjoy/pass/index?extraData=' + extraData,
  success: (res) => {
  },
  fail: (res) => {
  }
});

商家 App/H5拉起签约页

如果是商家 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%25252522partner_id%25252522%2525253A%252525222088301614697946%25252522%2525252C%25252522template_id%25252522%2525253A%2525252220200312000209030100008736478%25252522%2525252C%25252522out_request_no%25252522%2525253A%2525252288888888efd8f34536e88bf60cd7%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%25253DO3VQnXTLmk3OAqWO5G%2525252Bl9Y0uBMhHmCAmc6zKEL0%2525252FIE5mt0Enyt%2525252BjGAVjA0NkNN%2525252BU04F%2525252Fu584owWe3P6ctzvdhyHWfesYIxuWhFjqWOZdqV8s2HSdrhjXdB4dOlTUi73cjAHkKYiCMuttaVxIS%2525252F6dUdiuYbHuolEtKFxU2oI2IBQBgBPURFWRc8fug22sQz4LjWuoVKloFMKzVIUJiHsgmGGEpTZKZDOQpdKA9o1EBB4Lq33s3%2525252BWAYrwkeDmDbuI%2525252FYinusxKuWOC9L0zHeXlZBcmwrUU7aClAlCXz0BwkBFh9Mhf0saxFS3%2525252FiHyQpaj8sjYRXjAh2qmEbwYJN6RKQlQ%2525253D%2525253D%252526sign_type%25253DRSA2%252526timestamp%25253D2021-03-07%25252B14%2525253A08%2525253A09%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==

通知参数说明

商户需保存 agreement_id，后续的系统交互都以 agreement_id 识别用户身份，具体消息属性可查看 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 普通版

开通流程图#

第一步：获取用户授权#

第二步：签约预创单（可选）#

参数说明#

第三步：拉起签约页#

构造签约的 URL#

请求示例#

响应示例#

拉起签约页#

支付宝小程序拉起签约页#

商家 App/H5拉起签约页#

完整 schema 示例#

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

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

消息通知#

消息订阅注意事项#

第一步：验签#

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

成功开通通知#

消息通知示例#

通知参数说明#

跳转芝麻 GO 管理页#