开通流程

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

第一步：获取用户授权

商家可通过用户授权获取用户支付宝 ID 即 user_id。

说明：

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

若还需获取用户其它支付宝信息，如手机号等，就需要弹出用户授权框，用户确认后才可获取，从用户转化来讲，建议尽量只获取支付宝 user_id 即可，用 userid 来绑定支付宝用户和商家会员之间的关系。

第二步：拉起签约页

构造签约的 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\"," +
"\"out_request_no\":\"8077735255938032\"" +
"}");
ZhimaCreditPeZmgoSignApplyResponse response = alipayClient.pageExecute(request,"GET");
// 获取OpenAPI调用URL，主要获取后面的参数
String openUrl=response.getBody();

其中 biz_content 中对应参数：

参数	描述	是否必填	举例
partner_id	商家 ID。	是	2088301614697946
template_id	模板 ID。	是	2019071000020903940000062019
out_request_no	外部请求号，商家自定义。	是	8077735255938032

响应示例

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 指定页面的话 URL 换成对应的内容。

拉起签约页

支付宝小程序拉起签约页

如果是商家支付宝小程序拉起签约页，需通过调用 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 拉起签约页

如果是商家 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=。
**注意：**前缀内容全部为固定值，无需修改。

// 原始参数字符串
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 识别用户身份。

商家需以 type=CYCLE_WITHHOLD 来判断，是否为 周期扣。

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

actual_price 为发起的 实扣金额。

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

如果用户在 exemption_end_time 这个时间之前发起退出，那后续发起芝麻GO扣款时，传入金额必须为 0。exemption_end_time 为豁免期。

具体消息属性可查看 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 拉起签约页#

完整 schema 示例#

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

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

消息通知#

消息订阅注意事项#

第一步：验签#

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

成功开通通知#

消息通知示例#

通知参数说明#

跳转芝麻 GO 管理页#