资源中心芝麻认证快速接入
您可以点击纯净版进行查看

开始接入

欢迎你成为芝麻信用的商户,在开始接口调用之前请先确保完成以下事项:

  1. 完成 商户入驻 流程,并已经完成本 产品签约
  2. 你需要获取一个 应用 ID,并完成必要的开发 环境配置
  3. 芝麻开放平台通过 HTTPS 通信进行接口调用,包含系统调用和页面转跳两类接口,相关概念参照 接口调用;参数的加密解密和加签验签参考 介绍文档
  4. 业务流水凭证(transaction_id)是商户与芝麻信用系统产生业务交互的唯一凭证,生成规则参考 业务流水凭证
  5. 部分芝麻信用产品需要商户进行数据反馈,参考文档 数据反馈 部分;
  6. 入参中包含 open_id 的产品需要进行 用户授权
  7. 芝麻开放平台提供了 Java 1.5、Java 1.4 、PHP 和 .NET 的服务端 SDK 供商家快速接入服务使用,SDK 能够在 开发工具包下载页 获取。

总体流程

  1. 调用 customer.certification.initialize 接口进行认证初始化,并获取返回值 biz_nobiz_no 是本次认证的标识,在后面的认证接口和查询接口会用到。
  2. 跳转到 customer.certification.certify 页面接口或者使用客户端 SDK 让用户完成认证,用户完成认证后会通知商户结果。这个接口支持多种方式接入,可以灵活使用。必须在这个接口的请求中传入 return_url 才能回跳到商户, return_url 也支持多个协议,可以按照需要使用。接入方式和回调协议案例参考下面的 demo。
  3. 可以根据第一步返回的 biz_no 查询本次认证的状态和结果。

场景介绍

芝麻认证支持几种认证场景,不同的商户在不同的业务场景可以选择使用不用的认证场景。认证场景的总体接入流程如上面介绍都是一样的,主要区别在于开始认证步骤。认证场景相关介绍可以参考产品文档。认证场景和认证场景码(biz_code)对照表如下

?

认证场景 多因子人脸认证 多因子快捷人脸认证 多因子证件照片认证 多因子证件照片和人脸认证 人脸认证SDK
认证场景码 FACE SMART_FACE CERT_PHOTO CERT_PHOTO_FACE FACE_SDK

下面根据认证终端分别介绍业务接入流程。

认证初始化

使用服务端接口:zhima.customer.certification.initialize。接口详情参照 认证初始化文档

调用代码示例:

ZhimaCustomerCertificationInitializeRequest request = new ZhimaCustomerCertificationInitializeRequest();
request.setPlatform("zmop");
request.setTransactionId("ZGYD201610252323000001234");// 必要参数
request.setProductCode("w1010100000000002978");// 必要参数
request.setBizCode("FACE");// 必要参数
request.setIdentityParam("{\"identity_type\":\"CERT_INFO\",\"cert_type\":\"IDENTITY_CARD\",\"cert_name\":\"收委\",\"cert_no\":\"260104197909275964\"}");// 必要参数
request.setExtBizParam("{}");// 必要参数
DefaultZhimaClient client = new DefaultZhimaClient(
    "https://zmopenapi.zmxy.com.cn/openapi.do",
    "app_id",
    "your private_key",
    "zhima_public_key");
try {
    ZhimaCustomerCertificationInitializeResponse response = (ZhimaCustomerCertificationInitializeResponse) client
        .execute(request);
    System.out.println(response.isSuccess());
    System.out.println(response.getErrorCode());
    System.out.println(response.getErrorMessage());
} catch (ZhimaApiException e) {
    e.printStackTrace();
}

开始认证说明

开始认证方式根据认证终端不同(详见场景介绍),主要有两种方式可选,分别为:

  1. 支付宝客户端内认证,需要唤起支付宝客户端完成认证;
  2. 商户 App 认证,需要商户 App 接入芝麻认证 SDK 并在商户 App 内完成认证。

开始认证方式一:支付宝端内认证

1. 生成认证请求 URL

使用服务端接口:zhima.customer.certification.certify。接口详情参照 开始认证文档

必须要传回调地址 return_url,回调支持在支付宝 App 打开(示例:alipays://www.taobao.com )、在浏览器打开(示例:https://www.taobao.com )、在商户 App 打开(使用商户 schema 协议)。

ZhimaCustomerCertificationCertifyRequest request = new ZhimaCustomerCertificationCertifyRequest();
request.setPlatform("zmop");
request.setBizNo("ZM201612013000000242400404124269");// 必要参数
// 设置回调地址,必填. 如果需要直接在支付宝APP里面打开回调地址使用alipay协议
// alipay://www.taobao.com 或者 alipays://www.taobao.com,分别对应http和https请求
request.setReturnUrl("http://www.taobao.com");// 必要参数
DefaultZhimaClient client = new DefaultZhimaClient(
    "https://zmopenapi.zmxy.com.cn/openapi.do";, "app_id", "your private_key",
    "zhima_public_key");
try {
    String url = client.generatePageRedirectInvokeUrl(request);
    System.out.println("generateCertifyUrl url:" + url);
} catch (ZhimaApiException e) {
    e.printStackTrace();
}

2. 示例认证 URL

生成的 URL 必须包含回调地址

https://zmopenapi.zmxy.com.cn/openapi.do?sign=rr8lb07UarEXFp2gckiAc28y%2BeHHdq%2BYwWFBW3bl1iYMKK2ScHFYtZRdOxWwBgbqBily5P6455c4QjumfF%2BRQhHgFr6DrA7RfMDp3tQMbTAn7wtAR8vGE8o%2BuCKAgDMzF2lfqCSn%2BGcOtbhSwnNbJDJAsNWerlezkSTu0YrMLvA%3D&signtype=RSA&charset=UTF-8&appid=1000509&method=zhima.customer.certification.certify&version=1.0?ms=TNjy6EwBUey02QxJF4VUB4UjkRL1NjLHrK7XKD1J9sGvjvVPXGT7e1cupoxr%2BBZS1OXbhpf4LTRVzPIgROiyk6az%2BFFU7ud0378ugHn8UbqHu%2FvbeTRsEY0FDAekCv6AmY6xbVZRDkClVuM9k1KlZ6bVRvs%2F1zUgvjP8iSivKA0%3D

3. 开始认证方式 1:商户有自己的 App 使用 native 的方式唤起支付宝客户端(可选)

在商户 App 使用如下示例代码(传入认证 URL)使用 native 代码唤起支付宝客户端进行认证:

iOS 示例代码:

- (void)doVerify:(NSString )url {
   // 这里使用固定appid 20000067
    NNSString alipayUrl = [NSString stringWithFormat:@"alipays://platformapi/startapp?appId=20000067&url=%@", 
[self URLEncodedStringWithUrl:url]];
    if ([self canOpenAlipay]) {
        [[UIApplication sharedApplication] openURL:[NSURL URLWithString:alipayUrl] options:@{} completionHandler:nil];
    } else {
        UIAlertView alertView = [[UIAlertView alloc] initWithTitle:@"" message:@"是否下载并安装支付宝完成认证?" 
delegate:self cancelButtonTitle:@"取消" otherButtonTitles:@"好的", nil];
        [alertView show];
    }
}

- (NSString )URLEncodedStringWithUrl:(NSString )url {
    NSString encodedString = (NSString )CFBridgingRelease(CFURLCreateStringByAddingPercentEscapes(NULL,(CFStringRef)url,NULL,(CFStringRef) @"!'();:@&=+$,%#[]|",kCFStringEncodingUTF8));
    return encodedString;
}

- (void)alertView:(UIAlertView )alertView clickedButtonAtIndex:(NSInteger)buttonIndex {
    if (buttonIndex == 1) {
        NSString appstoreUrl = @"itms-apps://itunes.apple.com/app/id333206289";
        [[UIApplication sharedApplication] openURL:[NSURL URLWithString:appstoreUrl] options:@{} completionHandler:nil];
    }
}

- (BOOL)canOpenAlipay {
    return [[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:@"alipays://"]];
}

// 并且在Info.plist文件中配置alipays到LSApplicationQueriesSchemes参数中

Android 示例代码:

/**
 * 启动支付宝进行认证
 * @param url 开放平台返回的URL
 */
private void doVerify(String url) {
    if (hasApplication()) {
        Intent action = new Intent(Intent.ACTION_VIEW);
        StringBuilder builder = new StringBuilder();
       // 这里使用固定appid 20000067
        builder.append("alipays://platformapi/startapp?appId=20000067&url=");
        builder.append(URLEncoder.encode(url));
        action.setData(Uri.parse(builder.toString()));
        startActivity(action);
    } else {
        // 处理没有安装支付宝的情况
        new AlertDialog.Builder(this)
            .setMessage("是否下载并安装支付宝完成认证?")
            .setPositiveButton("好的", new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialog, int which) {
                Intent action = new Intent(Intent.ACTION_VIEW);
                action.setData(Uri.parse("https://m.alipay.com"));
                startActivity(action);
            }
        }).setNegativeButton("算了", new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialog, int which) {
                dialog.dismiss();
            }
        }).show();
    }
}

/**
 * 判断是否安装了支付宝
 * @return true 为已经安装
 */
private boolean hasApplication() {
    PackageManager manager = getPackageManager();
    Intent action = new Intent(Intent.ACTION_VIEW);
    action.setData(Uri.parse("alipays://"));
    List list = manager.queryIntentActivities(action, PackageManager.GET_RESOLVED_FILTER);
    return list != null && list.size() > 0;
}

4. 开始认证方式 2:商户没有自己的 App 使用 H5 页面的方式唤起支付宝客户端(可选)

在商户的 H5 页面跳转到认证 URL,进入芝麻认证引导页,芝麻认证引导页会唤起支付宝客户端。

5. 开始认证方式 3:根据认证 URL 生成二维码让用户打开支付宝客户端扫描(可选)

商户根据认证 URL 生成二维码,然后提供二维码让用户使用支付宝客户端扫码进入认证引导页。二维码生成示例代码点此 链接 下载。

开始认证方式二:商户App内认证

认证查询

使用服务端接口:zhima.customer.certification.query。接口详情参照 认证查询文档

调用代码示例:

ZhimaCustomerCertificationQueryRequest req = new ZhimaCustomerCertificationQueryRequest();
req.setPlatform("zmop");
req.setBizNo("ZM201612013000000242400404124269");// 必要参数
DefaultZhimaClient client = new DefaultZhimaClient(
        "https://zmopenapi.zmxy.com.cn/openapi.do", "app_id", "your private_key",
        "zhima_public_key");
try {
    ZhimaCustomerCertificationQueryResponse response =(ZhimaCustomerCertificationQueryResponse)client.execute(req);
    System.out.println(response.isSuccess());
    System.out.println(response.getErrorCode());
    System.out.println(response.getErrorMessage());
} catch (ZhimaApiException e) {
    e.printStackTrace();
}
  1. 开始接入
  2. 总体流程
  3. 场景介绍
  4. 认证初始化
  5. 开始认证说明
  6. 开始认证方式一:支付宝端内认证
  7. 开始认证方式二:商户App内认证
  8. 认证查询
onlineServer