当您使用 SDK 进行开发时,无需拼接 HTTPS 请求或实现签名算法,开发更方便。因此我们强烈建议您通过 SDK 方式在服务端集成金融级实人认证。金融级实人认证提供了 Java、Python、PHP、C#、Golang、Node.js 和 Ruby 语言的 SDK。

发起认证请求字段说明

发起认证请求时,传入以下字段:
名称 类型 是否必需 描述 示例值
method String 发起认证请求的操作。

取值必须是init

init
sceneId String 认证场景ID,在控制台创建认证场景后自动生成。 1000000006
outerOrderNo String 商户请求的唯一标识,值为32位长度的字母数字组合前面几位字符是商户自定义的简称,中间可以使用一段时间,后段可以使用一个随机或递增序列。 e0c34a77f5ac40a5aa5e6ed20c353888
bizCode String 认证场景码和用户发起认证的端有关:
  • 当用户在 iOS 或安卓平台发起认证时,认证场景码是 FACE_SDK
  • 当用户在小程序中或 H5 页面中发起认证时,认证场景码是 FACE
FACE_SDK
identityType String 身份信息参数类型,必须传入 CERT_INFO。 CERT_INFO
certType String 证件类型,当前支持身份证,必须传入IDENTITY_CARD。 IDENTITY_CARD
certNo String 用户身份证件号。 330103xxxxxxxxxxxx
certName String 用户姓名。 张三
returnUrl String 商户业务页面回调的目标地址。
  • 如您不需要回调商户业务页面,您可以在此处传入空字符串。
  • 当您采用端外唤起支付宝认证页面接入,且希望您的用户唤起支付宝完成认证后,能够跳回您的应用页面,您需要在此参数下传入您的应用的 Scheme。详情请参看:回跳原应用
https://www.aliyun.com
发起认证后,您会收到响应。相应参数列表如下:
名称 类型 是否必需 描述 示例值
certifyId String 认证ID,刷脸认证唯一标识。 7eff3ad26a9c7b68c511b9f35eb1a354
certifyUrl String 认证流程入口 URL。 https://picker.antcloudauth.aliyuncs.com/gateway.do?...

查询认证结果

查询认证结果时,传入以下字段:
名称 类型 是否必需 描述 示例值
method String 查询人脸比对结果的操作。

取值必须为query

query
certifyId String 认证ID,需与发起认证请求时返回的certifyId保持一致。 7eff3ad26a9c7b68c511b9f35eb1a354
sceneId String 认证场景ID,需与发起认证请求时的sceneId保持一致。 1000000006
发起查询后,您会收到响应。相应参数列表如下:
名称 类型 是否必需 描述 示例值
passed String 是否通过,通过为T,不通过为F。 T
identityInfo String 认证的主体信息,一般的认证场景返回为空。 "IdentityInfo": "{"cert_type":"IDENTITY_CARD","cert_no":"330103xxxxxxxxxxxx","cert_name":"张三"}"
materialInfo String 认证主体附件信息,主要为图片类材料,一般的认证场景都是返回空。 {"facial_picture_front":{ "FEATURE_FACE":"xydasf=="}}

SDK 使用说明

1. JAVA SDK

下载 JAVA SDK 源码:aliyun-openapijava-sdk

配置 Maven 依赖:
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-saf</artifactId>
    <version>1.0.2</version>
</dependency>
推荐依赖仲裁:
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <optional>true</optional>
    <version>4.5.0</version>
</dependency>
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.60</version>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.2</version>
</dependency>
				
说明
代码示例如下:
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.fastjson.JSON;
import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.http.ProtocolType;
import com.aliyuncs.profile.DefaultProfile;

public class FaceVerifyTest {
    public static void main(String[] args) throws IOException {
        DefaultProfile profile = DefaultProfile.getProfile("cn-shanghai", "<your-access-key-id>", "<your-access-key-secret>");
        IAcsClient client = new DefaultAcsClient(profile);

        CommonRequest request = new CommonRequest();
        request.setSysMethod(MethodType.POST);

        request.setSysDomain("saf.cn-shanghai.aliyuncs.com");
        request.setSysVersion("2017-03-31");
        request.setSysAction("ExecuteRequest");
        request.setSysProtocol(ProtocolType.HTTPS);

        // 业务详细参数
        Map<String, Object> serviceParams = new HashMap<String, Object>();

        // 发起认证请求
        serviceParams.put("method",  "init");
        serviceParams.put("sceneId",  "1000000006");    
        serviceParams.put("outerOrderNo",  "e0c34a77f5ac40a5aa5e6ed20c353888");
        serviceParams.put("bizCode", "FACE");  //当用户在iOS或安卓平台发起认证时,认证场景码是 FACE_SDK;在小程序中,认证场景码则为 FACE。
        serviceParams.put("identityType", "CERT_INFO");
        serviceParams.put("certType", "IDENTITY_CARD");        
        serviceParams.put("certNo", "330103xxxxxxxxxxxx");
        serviceParams.put("certName", "张三");
        serviceParams.put("returnUrl", "https://www.aliyun.com");

        /*
        // 查询认证结果
        serviceParams.put("method",  "query");
        serviceParams.put("certifyId", "7eff3ad26a9c7b68c511b9f35eb1a354");
        serviceParams.put("sceneId", "1000000006");
        */

        request.putBodyParameter("ServiceParameters", JSON.toJSONString(serviceParams));
        // 固定值,Service = fin_face_verify
        request.putBodyParameter("Service", "fin_face_verify");

        try {
            CommonResponse response = client.getCommonResponse(request);
            System.out.println(response.getData());
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            e.printStackTrace();
        }
    }
}

2. Python SDK

下载 Python SDK 源码

  1. 安装 SDK 核心库。
    • 如果您使用Python 2.x,执行以下命令,安装阿里云SDK核心库:
      pip install aliyun-python-sdk-core
    • 如果您使用Python 3.x,执行以下命令,安装阿里云SDK核心库:
      pip install aliyun-python-sdk-core-v3
  2. 安装云产品 SAF SDK。
    pip install aliyun-python-sdk-saf

示例代码如下:

from aliyunsdkcore import client
from aliyunsdksaf.request.v20170331 import ExecuteRequestRequest

clt = client.AcsClient('<your-access-key-id>','<your-access-key-secret>','cn-shanghai')

# 设置参数
request = ExecuteRequestRequest.ExecuteRequestRequest()
request.set_accept_format('json')
# 产品Service请参考[公共参数]文档中的Service字段描述
request.add_query_param('Service', '购买的产品Service')
request.add_query_param('ServiceParameters', '入参json字符串')

# 发起请求
response = clt.do_action_with_exception(request)
print(response)
说明 Python SDK的环境准备、安装使用可参考:阿里云SDK开发指南

3. PHP SDK

引用 PHP SDK

代码示例:
<?php
require __DIR__ . '/vendor/autoload.php';
use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\Client\Exception\ClientException;
use AlibabaCloud\Client\Exception\ServerException;

// 设置一个全局客户端
// 需要替换 access-key-id 和 access-key-secret
AlibabaCloud::accessKeyClient('<access-key-id>', '<access-key-secret>')
            ->regionId('cn-shanghai')
            ->asDefaultClient();

// -- 下述参数依照实际使用的接口做调整,本演示仅针对认证初始化接口
$serviceParams = array(
    "method"=>       "init",
    "sceneId"=>      "1000000006",
    "outerOrderNo"=> "e0c34a77f5ac40a5aa5e6ed20c353903",
    "bizCode"=>      "FACE",
    "identityType"=> "CERT_INFO",
    "certType"=>     "IDENTITY_CARD",
    "certNo"=>       "330011200102257788",
    "certName"=>     "拉斯穆",
    "returnUrl"=>    "https://www.aliyun.com");
// --

try {
    // -- 下述参数无需调整
    $result = AlibabaCloud::rpcRequest() 
                           ->product('saf') 
                           ->scheme('https')
                           ->version('2017-03-31')
                           ->action('ExecuteRequest') 
                           ->method('POST')
                           ->host('saf.cn-shanghai.aliyuncs.com')
                           ->options([
                                         'query' => [
                                             'Service' => 'fin_face_verify',
                                             'ServiceParameters' => json_encode($serviceParams)
                                         ],
                                     ])
                           ->request();
    // -- 
    echo($result);
} catch (ClientException $exception) {
    echo $exception->getMessage() . PHP_EOL;
} catch (ServerException $exception) {
    echo $exception->getMessage() . PHP_EOL;
    echo $exception->getErrorCode() . PHP_EOL;
    echo $exception->getRequestId() . PHP_EOL;
    echo $exception->getErrorMessage() . PHP_EOL;
}

?>
说明 PHP SDK 的环境准备、安装使用可参考:阿里云SDK开发指南

4. C# SDK

下载 C# SDK 源码

参考 C# SDK 的环境准备和安装使用:阿里云SDK开发指南

5. Golang SDK

下载 Golang SDK

Golang 示例代码:
package main

import (
    "encoding/json"
    "fmt"

    "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
    "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
)

// ResponseContent 返回体
type ResponseContent struct {
    Data      map[string]string `json:"data"`
    RequestID string            `json:"requestId"`
    Code      string            `json:"code"`
    Message   string            `json:"message"`
}

func main() {
    // 需要替换 access-key-id 和 access-key-secret
    client, err := sdk.NewClientWithAccessKey(
        "cn-shanghai", "<access-key-id>", "<access-key-secret>")
    request := requests.NewCommonRequest()
    // -- 下述参数无需调整
    request.Domain = "saf.cn-shanghai.aliyuncs.com"
    request.Version = "2017-03-31"
    request.ApiName = "ExecuteRequest"
    request.Scheme = "https"
    request.QueryParams["Service"] = "fin_face_verify"
    // --

    // -- 下述参数依照实际使用的接口做调整,本演示仅针对认证初始化接口
    serviceParam := map[string]string{
        "method":       "init",
        "sceneId":      "1000000006",
        "outerOrderNo": "e0c34a77f5ac40a5aa5e6ed20c353900",
        "bizCode":      "FACE",
        "identityType": "CERT_INFO",
        "certType":     "IDENTITY_CARD",
        "certNo":       "330011202002257788",
        "certName":     "罗伯特·格瑞史莫",
        "returnUrl":    "https://www.aliyun.com",
    }
    // --
    serviceParamByte, err := json.Marshal(serviceParam)
    if err != nil {
        panic(err)
    }
    request.QueryParams["ServiceParameters"] = string(serviceParamByte)

    response, err := client.ProcessCommonRequest(request)
    if err != nil {
        panic(err)
    }
    respContent := ResponseContent{}
    err = json.Unmarshal(response.GetHttpContentBytes(), &respContent)
    fmt.Printf("response data is %#v\n", respContent.Data)
    fmt.Println("end")
}
说明 Golang SDK的环境准备、安装使用可参考:阿里云SDK开发指南

6. Node.js SDK

下载 Node.js SDK 源码

执行以下命令安装@alicloud/pop-core模块。命令中的--save会将模块写入应用的package.json文件中,作为依赖模块。
$ npm install @alicloud/pop-core --save
Node.js 代码示例:
const Core = require('@alicloud/pop-core');

// 需要替换 access-key-id 和 access-key-secret
var client = new Core({
  accessKeyId: '<access-key-id>',
  accessKeySecret: '<access-key-secret>',
  endpoint: 'https://saf.cn-shanghai.aliyuncs.com',
  apiVersion: '2017-03-31'
});

// -- 下述参数依照实际使用的接口做调整,本演示仅针对认证初始化接口
var serviceParams = {
    "method":       "init",
    "sceneId":      "1000000006",
    "outerOrderNo": "e0c34a77f5ac40a5aa5e6ed20c353901",
    "bizCode":      "FACE",
    "identityType": "CERT_INFO",
    "certType":     "IDENTITY_CARD",
    "certNo":       "330011200102257788",
    "certName":     "瑞安·达尔",
    "returnUrl":    "https://www.aliyun.com"
}
// --

var params = {
  "RegionId": "cn-shanghai",
  "Service": "fin_face_verify",
  "ServiceParameters": JSON.stringify(serviceParams)
}

var requestOption = {
  method: 'POST'
};

client.request('ExecuteRequest', params, requestOption).then((result) => {
  console.log(JSON.stringify(result));
}, (ex) => {
  console.log(ex);
})
说明 Node.js SDK 的环境准备、安装使用可参考:阿里云SDK开发指南

7. Ruby SDK

下载 Ruby SDK 源码

执行以下命令安装 Alibaba Cloud Core SDK for Ruby:
$ gem install aliyunsdkcore
Ruby 代码示例:
require 'aliyunsdkcore'

client = RPCClient.new(
  access_key_id:     '<your-access-key-id>',
  access_key_secret: '<your-access-key-secret>',
  endpoint: 'https://saf.cn-shanghai.aliyuncs.com',
  api_version: '2017-03-31'
)

response = client.request(
  action: 'ExecuteRequest',
  params: {
    "RegionId": "cn-shanghai",
    # 产品Service请参考[公共参数]文档中的Service字段描述
    "Service": "购买的产品Service",
    "ServiceParameters": "入参json字符串"
  },
  opts: {
    method: 'POST'
  }
)

print response
说明 Ruby SDK 的环境准备、安装使用可参考:阿里云SDK开发指南