完成接入准备后，商家/服务商可根据本文指引快速接入 芝麻****工作证 产品。

说明：

芝麻****工作证 产品暂不支持沙箱调试。

芝麻****工作证 产品支持自研商家/服务商通过自研应用或第三方应用代调用方式接入。

完整接口时序图

商户发起身份验证与同步/异步查询验证结果的流程。

发起身份验真

包含一次完整的用户身份验真流程。

流程描述

商家/服务商需调用 zhima.credit.payafteruse.creditagreement.sign（信用服务开通/授权接口）生成签名 SignStr。

通过 JSAPI 或 拼接跳转链接 拉起支付宝端完成用户身份验证授权及身份验真。

生成签名

商家/服务商需调用 zhima.credit.payafteruse.creditagreement.sign（信用服务开通/授权接口

）生成签名。

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");

ZhimaCreditPayafteruseCreditagreementSignRequest request = new ZhimaCreditPayafteruseCreditagreementSignRequest();

// ------------------------- 商户需要配置的入参 start --------------------------------
String outAgreementNo = "xxxxx"; // 自定义授权单号，如果更换单号，会让用户重新授权，支持数字和常见字母，长度限制128位，不支持特殊字符
String onceToken = "xxx";        // 查询身份验证结果的令牌，单次快照结果，若要获取最新的身份验证结果或者更换验证身份，需要更换once_token，支持数字和常见字母，长度限制128位，不支持特殊字符
String queryType = "exact";      // 验真精度，exact : 严格，dim : 模糊
String identityType = "05";      // 验真职业身份，05代表医护，04代表教师
String zmServiceId = "xxx";      // 商户信用服务id，通过验真服务资源申请获取
// ------------------------- 商户需要配置的入参 end --------------------------------

JSONObject extraParam = new JSONObject()
     .fluentPut("identity_type",identityType)
     .fluentPut("once_token",onceToken)
     .fluentPut("query_type",queryType);
JSONObject bizContent = new JSONObject()
     .fluentPut("out_agreement_no",outAgreementNo)
     .fluentPut("zm_service_id",zmServiceId)
     .fluentPut("category_id","ZHIMA_AUTH")
     .fluentPut("cancel_back_link","")
     .fluentPut("return_back_link","")
     .fluentPut("extra_param",extraParam.toJSONString())
     .fluentPut("product_code","ZHIMA_AUTH");
request.setBizContent(JSON.toJSONString(bizContent));

ZhimaCreditPayafteruseCreditagreementSignResponse response = alipayClient.pageExecute(request, "GET");

// 获取接口返回的地址
String openUrl = response.getBody();

响应示例

https://openapi.alipay.com/gateway.do?bizmock_trace_id=ab6b59cc1b51488ca9f518853e46c0ed219968&charset=GBK&biz_content=%7B%22zm_service_id%22%3A%2220200507220014400310061082%22%2C%22category_id%22%3A%22credit_pay_after_use%22%2C%22cancel_back_link%22%3A%22https%3A%2F%2Fwww.taobao.com%22%2C%22return_back_link%22%3A%22https%3A%2F%2Fwww.taobao.com%22%2C%22product_code%22%3A%22CREDIT_PAY_AFTER_USE%22%2C%22extra_param%22%3A%22%7B%5C%22merchantExt%5C%22%3A%5C%22key%3Dvalue%5C%22%7D%22%2C%22out_agreement_no%22%3A%222014070700166653%22%7D&method=zhima.credit.payafteruse.creditagreement.sign&format=json&sign=rBLvTzvkSL%2BW%2FAxb%2B7%2FBTJKB7z7iiXKusW5689FiiQuVGjwAaWyzR1QmIywPgZm0gFqhL1ZCAgwpInBrJO1RSGCaupH3hPO%2F7%2FR1JOVvr12tdReocHxYj%2FP52mbnVsWk2EN%2F2IihA9sX94KZSMovP5dVx2ooq4PDV11RvZnhfXorsS3iGfHD9O7WvGKp4F4nMsmFDzrGUsMVsm06XPRjwzh7WNiJzC0%2FRN3OJrgZNjUsX2GfMAuzeh1sm1PD5FV%2Bd6OUEROf6NZOmeS5349qrnaJYG0yry69FkSmhvnOA9%2BQW9KopxSefk%2BcfYfXv3E6jNDXV5k4A5w%3D%3D&app_id=2019101168279633&version=1.0&sign_type=RSA2&timestamp=2021-06-30+14%3A23%3A39

更多请求、响应参数说明及错误码详情，可查看 zhima.credit.payafteruse.creditagreement.sign（信用服务开通/授权接口）文档。

获取签名

截取返回结果中问号后面的内容后面的作为 signStr（签名）。

bizmock_trace_id=ab6b59cc1b51488ca9f518853e46c0ed219968&charset=GBK&biz_content=%7B%22zm_service_id%22%3A%2220200507220014400310061082%22%2C%22category_id%22%3A%22credit_pay_after_use%22%2C%22cancel_back_link%22%3A%22https%3A%2F%2Fwww.taobao.com%22%2C%22return_back_link%22%3A%22https%3A%2F%2Fwww.taobao.com%22%2C%22product_code%22%3A%22CREDIT_PAY_AFTER_USE%22%2C%22extra_param%22%3A%22%7B%5C%22merchantExt%5C%22%3A%5C%22key%3Dvalue%5C%22%7D%22%2C%22out_agreement_no%22%3A%222014070700166653%22%7D&method=zhima.credit.payafteruse.creditagreement.sign&format=json&sign=rBLvTzvkSL%2BW%2FAxb%2B7%2FBTJKB7z7iiXKusW5689FiiQuVGjwAaWyzR1QmIywPgZm0gFqhL1ZCAgwpInBrJO1RSGCaupH3hPO%2F7%2FR1JOVvr12tdReocHxYj%2FP52mbnVsWk2EN%2F2IihA9sX94KZSMovP5dVx2ooq4PDV11RvZnhfXorsS3iGfHD9O7WvGKp4F4nMsmFDzrGUsMVsm06XPRjwzh7WNiJzC0%2FRN3OJrgZNjUsX2GfMAuzeh1sm1PD5FV%2Bd6OUEROf6NZOmeS5349qrnaJYG0yry69FkSmhvnOA9%2BQW9KopxSefk%2BcfYfXv3E6jNDXV5k4A5w%3D%3D&app_id=2019101168279633&version=1.0&sign_type=RSA2&timestamp=2021-06-30+14%3A23%3A39

基于签名构造支付宝身份验真受理台跳转链接

提供两种方式构造，直接跳转链接模式 与 JSAPI模式，商家可按需进行选择。

直接跳转链接模式

先根据 signStr，构造 schemeUrl。

构造规则：

'alipays://platformapi/startapp?appId=20000067&url=' + encodeURIComponent('https://render.alipay.com/p/yuyan/180020010000706007/index.html?signStr='+ encodeURIComponent(signStr))

示例：

alipays://platformapi/startapp?appId=20000067&url=https%3A%2F%2Frender.alipay.com%2Fp%2Fyuyan%2F180020010000706007%2Findex.html%3FsignStr%3Dbizmock_trace_id%253D5fcca2b0c6254b01b3df99be03e61af2189008%2526charset%253DGBK%2526biz_content%253D%25257B%252522zm_service_id%252522%25253A%2525222021020500000000000004336900%252522%25252C%252522category_id%252522%25253A%252522credit_payment_000001%252522%25252C%252522cancel_back_link%252522%25253A%252522https%25253A%25252F%25252Fwww.taobao.com%252522%25252C%252522external_logon_id%252522%25253A%252522138552852877%252522%25252C%252522return_back_link%252522%25253A%252522https%25253A%25252F%25252Fwww.taobao.com%252522%25252C%252522out_request_no%252522%25253A%252522120139139882423%252522%25252C%252522extra_param%252522%25253A%252522%25257B%25255C%252522merchantExt%25255C%252522%25253A%25255C%252522key%25253Dvalue%25255C%252522%25257D%252522%25252C%252522out_agreement_no%252522%25253A%2525222014070ddd70550166653%252522%25257D%2526method%253Dzhima.credit.payafteruse.creditagreement.sign%2526format%253Djson%2526sign%253DRGKmqiVk3DfkGJT4ZetTKcieqVXRXr64kO9SudS4j4VA6vlsHp5mAUKgB9JqbHMUpdcXm8YY%25252BgiqZqZn%25252BkQj%25252BEkiIr%25252BRDhivv0m8%25252FHSxO2nYWCdT86OZ%25252BrmVbVZP3H3vDA5whLLBG7sS6E1jnBvNN1ppPJhCCfvxSwQRHbg8qSaf8Ue7kovf%25252Ftfs5dJ9%25252FXRXVYmMJSKibDHoD%25252BDSMsSBNOfr6uDdXNtIHMK%25252FjXijhb7WUFntyxlJl6eJN3BDHSgB9RIdaiFgnfj5Xh1QyD%25252B2W%25252BH%25252B178MJ6%25252FF6r6BHyZIKqAQeaVs2vIlsHtQtTILQ0u01ugBfoTxvCfkXGHcm8hDIg%25253D%25253D%2526app_id%253D2017090501336036%2526version%253D1.0%2526sign_type%253DRSA2%2526timestamp%253D2021-07-12%252B19%25253A59%25253A49

注意：完成后，如果是商家的程序是支付宝端内应用就可以直接使用 schemeUrl 拉起受理台，否则还需基于 schemeUrl去构造 landingUrl才能访问。构造规则如下。

构造规则：

'https://render.alipay.com/p/s/i/?scheme=' +  encodeURIComponent(schemeUrl)

示例：

https://render.alipay.com/p/s/i/?scheme=alipays%3A%2F%2Fplatformapi%2Fstartapp%3FappId%3D20000067%26url%3Dhttps%253A%252F%252Frender.alipay.com%252Fp%252Fyuyan%252F180020010000706007%252Findex.html%253FsignStr%253Dbizmock_trace_id%25253D5fcca2b0c6254b01b3df99be03e61af2189008%252526charset%25253DGBK%252526biz_content%25253D%2525257B%25252522zm_service_id%25252522%2525253A%252525222021020500000000000004336900%25252522%2525252C%25252522category_id%25252522%2525253A%25252522credit_payment_000001%25252522%2525252C%25252522cancel_back_link%25252522%2525253A%25252522https%2525253A%2525252F%2525252Fwww.taobao.com%25252522%2525252C%25252522external_logon_id%25252522%2525253A%25252522138552852877%25252522%2525252C%25252522return_back_link%25252522%2525253A%25252522https%2525253A%2525252F%2525252Fwww.taobao.com%25252522%2525252C%25252522out_request_no%25252522%2525253A%25252522120139139882423%25252522%2525252C%25252522extra_param%25252522%2525253A%25252522%2525257B%2525255C%25252522merchantExt%2525255C%25252522%2525253A%2525255C%25252522key%2525253Dvalue%2525255C%25252522%2525257D%25252522%2525252C%25252522out_agreement_no%25252522%2525253A%252525222014070ddd70550166653%25252522%2525257D%252526method%25253Dzhima.credit.payafteruse.creditagreement.sign%252526format%25253Djson%252526sign%25253DRGKmqiVk3DfkGJT4ZetTKcieqVXRXr64kO9SudS4j4VA6vlsHp5mAUKgB9JqbHMUpdcXm8YY%2525252BgiqZqZn%2525252BkQj%2525252BEkiIr%2525252BRDhivv0m8%2525252FHSxO2nYWCdT86OZ%2525252BrmVbVZP3H3vDA5whLLBG7sS6E1jnBvNN1ppPJhCCfvxSwQRHbg8qSaf8Ue7kovf%2525252Ftfs5dJ9%2525252FXRXVYmMJSKibDHoD%2525252BDSMsSBNOfr6uDdXNtIHMK%2525252FjXijhb7WUFntyxlJl6eJN3BDHSgB9RIdaiFgnfj5Xh1QyD%2525252B2W%2525252BH%2525252B178MJ6%2525252FF6r6BHyZIKqAQeaVs2vIlsHtQtTILQ0u01ugBfoTxvCfkXGHcm8hDIg%2525253D%2525253D%252526app_id%25253D2017090501336036%252526version%25253D1.0%252526sign_type%25253DRSA2%252526timestamp%25253D2021-07-12%25252B19%2525253A59%2525253A49

直接跳转这个landingUrl，这个时候会先到一个中间landing页面引导用户下载支付宝。

JSAPI方式

注意：JSAPI 只能在真机测试无法在小程序 IDE 中使用。

H5

AlipayJSBridge.call('startBizService', {
  name: 'openCreditEvaluation', // 
  param: '{\"signStr\":\"\"}', // 
}, function(result){
  alert(JSON.stringify(result)); // 
  // 调用同步获取身份验真结果接口获取最新验证状态
    invoke openapi:zhima.customer.jobworth.authentication.query
});

请求参数

属性	类型	必填	描述
name	String	是	固定值 openCreditEvaluation。
signStr	String	是	签名字符串。可通过上文的生成签名步骤获取到。
function	Function	否	调用成功，半屏关闭的回调函数。

**
**

小程序

方式一：

my.ap.openCreditEvaluation({
 signStr: '',  //只是工作证授权不需要改参数
  success: (res) => {
    // 调用成功，半屏关闭的回调函数。如果调用方需要半屏关闭后进行一些操作，可以在这个回调函数里处理。
    // 比如页面状态的刷新
      
      // 调用同步获取身份验真结果接口获取最新验证状态
    invoke openapi:zhima.customer.jobworth.authentication.query
  }
})

请求参数

属性	类型	必填	描述
signStr	String	是	签名字符串。可通过上文的生成签名步骤获取到
success	Function	否	调用成功，半屏关闭的回调函数。

方式二：

my.call('startBizService', {
  name: 'openCreditEvaluation', // 
  param: '{\"signStr\":\"\"}', // 
}, (result) => {
    // 调用同步获取身份验真结果接口获取最新验证状态
    invoke openapi:zhima.customer.jobworth.authentication.query
});

请求参数

属性	类型	必填	描述
name	String	是	固定值 openCreditEvaluation。
signStr	String	是	签名字符串。可通过上文的生成签名步骤获取到。
function	Function	否	调用成功，半屏关闭的回调函数。

**
**

小程序使用限制

基础库 2.7.7 或更高版本；若版本较低，建议采取兼容处理。

if (my.canIUse('ap.openCreditEvaluation')) {
  my.ap.openCreditEvaluation({
    signStr: '',
    success: (res) => {
      my.alert({
        title: JSON.stringify(res),
      });
      // 调用同步获取身份验真结果接口获取最新验证状态
    invoke openapi:zhima.customer.jobworth.authentication.query
    },
  });
} else {
  const param = {
    signStr: '',
  };
  my.call(
    'startBizService',
    {
      name: 'openCreditEvaluation', //
      param: JSON.stringify(param), //
    },
    function (result) {
      alert(JSON.stringify(result)); //
      // 调用同步获取身份验真结果接口获取最新验证状态
    invoke openapi:zhima.customer.jobworth.authentication.query
    },
  );
}

同步获取身份验真结果

用户回到商家小程序内后由商家调用 zhima.customer.jobworth.authentication.query（职得身份认证查询接口）查询用户身份验证结果。

请求示例

ApiClient apiClient = Configuration.getDefaultApiClient();
// 初始化alipay参数（全局设置一次）
AlipayConfig alipayConfig = new AlipayConfig();
alipayConfig.setServerUrl("https://openapi.alipay.com");
alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
apiClient.setAlipayConfig(alipayConfig);
ZhimaCustomerJobworthAuthenticationApi api = new ZhimaCustomerJobworthAuthenticationApi();
// ------------------------- 商户需要配置的入参 start --------------------------------
String connKey = "xxxxx"; // 授权单号，就是完成授权步骤中商户传入的outAgreementNo，为zhima.credit.payafteruse.creditagreement.sign接口的入参
String onceToken = "xxx";        // 查询身份验证结果的令牌，为zhima.credit.payafteruse.creditagreement.sign接口的入参
String queryType = "exact";      // 验真精度，exact : 严格，dim : 模糊
String identityType = "05";      // 验真职业身份，05代表医护，04代表教师,03代表学生
String serviceId = "xxx";      // 商户信用服务id，通过验真服务资源申请获取
String userId = "xxx";      // 用户支付宝uid,如果传入了certNo和certType字段的话，该字段就非必传
String certNo = "xxx";      // 用户证件号,如果传入了该userId字段，该字段就非必传
String certType = "0";      // 用户证件类型,如果传入了该userId字段，该字段就非必传
// ------------------------- 商户需要配置的入参 end --------------------------------
try {
    ZhimaCustomerJobworthAuthenticationQueryResponseModel response = api.query(connKey, onceToken, queryType,
            identityType, serviceId, userId, null, certNo, certType);
    System.out.println(response);
} catch (ApiException e) {
    System.out.println("调用失败，code：" + e.getCode() + "，body：" + e.getResponseBody());
}

响应示例

{
    "token_status":"FINISH",
    "user_id":"2088402562742105",
    "identity_result":"SUCCESS/FAILED/WAITING_VERIFY",
    "identity_result_skip_url":"alipays://platformapi/startapp?appId"
}

更多请求、响应参数说明及错误码详情，可查看 zhima.customer.jobworth.authentication.query（职得身份认证查询接口）文档。

异步身份验证消息通知接口 (可选)

说明：若商家不需要监听消息异步获取验真结果，可跳过该步。

需要去后台订阅消息接口 zhima.customer.jobworth.authentication.notify（工作证身份验真消息通知接口）。如果选用 HTTP 协议接受异步消息需要进行结果验签，详情可查看 From 蚂蚁消息服务使用。

如某商家设置的通知地址为 https://api.xx.com/receive_notify.htm，对应接收到通知的示例如下：

https://api.xx.com/receive_notify.htm?charset=GBK&biz_content=
{
"conn_key":"uuid",
"once_token":"uuid",
"query_type":"exact/dim",
"identity_type":"01",
"service_id":"2019120400000000000004450100",
"user_id":"20881999291212",
"identity_result":"success"
}
&msg_method=zhima.customer.jobworth.authentication.notify&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

在通知返回参数列表中，除去 sign、sign_type 两个参数外，凡是通知返回回来的参数皆是待验签的参数。

将剩下参数进行 url_decode, 然后进行字典排序，组成字符串，得到待签名字符串：

gmt_create=2015-06-1122:33:46&gmt_payment=2015-06-1122:33:59&notify_id=42af7baacd1d3746cf7b56752b91edcj34&notify_time=2015-06-1122:34:03&notify_type=trade_status_sync&out_trade_no=21repl2ac2eOutTradeNo322&seller_email=testyufabu07@alipay.com&seller_id=2088211521646673&subject=xxx中文&trade_no=2015061121001004400068549373&trade_status=TRADE_SUCCESS

将签名参数（sign）使用 base64 解码为字节码串。

使用 RSA/RSA2 的验签方法，通过签名字符串、签名参数（经过 base64 解码）及支付宝公钥验证签名。

注意：验证不通过，则表明本次通知是异常通知，务必忽略。

接入指南

完整接口时序图#

发起身份验真#

流程描述#

生成签名#

请求示例#

响应示例#

获取签名#

基于签名构造支付宝身份验真受理台跳转链接#

直接跳转链接模式#

JSAPI方式#

H5#

小程序#

方式一：#

方式二：#

同步获取身份验真结果#

请求示例#

响应示例#

异步身份验证消息通知接口 (可选)#

完整接口时序图

发起身份验真

流程描述

生成签名

请求示例

响应示例

获取签名

基于签名构造支付宝身份验真受理台跳转链接

直接跳转链接模式

JSAPI方式

H5

小程序

方式一：

方式二：

同步获取身份验真结果

请求示例

响应示例

异步身份验证消息通知接口 (可选)