# 二、人脸识别文档

# 人脸识别场景说明

人脸识别通过识别用户人脸，获取用户信息（openid）。

此功能常用于商户会员、商品推荐等场景，此流程无法用于支付。

FACEID-ONCE为直接启动人脸识别流程。

# 接入过程

# 人脸识别FACEID-ONCE模式时序图

sequenceDiagram participant A as 商户APP participant B as 微信人脸sdk participant D as 商户server participant C as 微信支付后台API Note over A, C: Step 1：程序启动时初始化 A ->> B: 1. 程序启动时初始化 initWxpayface B -->> A: 返回初始化结果 Note over A, C: Step 2：获取数据、SDK调用凭证 A ->> B: 2. 获取数据 getWxpayfaceRawdata B -->> A: 返回rawdata A ->> D: 3. 获取人脸SDK调用凭证 D ->> C: get_wxpayface_authinfo(rawdata) C -->> D: 返回authinfo D -->> A: 返回authinfo Note over A, C: Step 3：获取用户信息，返回人脸识别结果 A ->> B: 4. 获取用户信息 getWxpayfaceUserInfo(authinfo) activate B B ->> B: 调用摄像头, 启动人脸识别 B ->> B: 完成人脸检测/识别 B -->> A: 返回人脸识别结果(openid,nickname) Note over A, C: 执行商户侧的逻辑 A ->> B: 5. 释放资源 releaseWxpayface

# SDK调用

# 使用方式

SDK需要集成到商户应用，提供的SDK为C动态链接库dll，请注意采用cdecl调用约定
业务⽅C/C++技术栈可通过编译链接或者LoadLibrary的⽅式加载dll，并执行相关函数，C#等.NET平台的技术栈请参照下面C#导入DLL声明部分实现调用
运行时，需要先启动WxpayFaceService刷脸服务，然后商户应用使用SDK中的接口调起刷脸功能

注意点：

关于函数中⼊参、出参的数据格式, 均采⽤JSON字符串，编码为UTF-8。
调用wxpayCallFaceService成功后，务必调用wxpayReleaseResponse来释放响应结果

# 入口函数原型

/**
 * 调用人脸服务
 * @param reqBuf 	请求参数(JSON字符串)
 * @param reqSize 	请求参数长度
 * @param pRespBuf	用来接收响应结果(JSON字符串)的char**指针
 * @param pRespSize 用来接收响应结果长度的unsigned int*指针
 * @return 如果成功返回0，失败则返回非0
 */
extern "C" int wxpayCallFaceService(const char *reqBuf, unsigned int reqSize, char **pRespBuf, unsigned int *pRespSize);


/**
 * 释放人脸服务的响应字符串，调用wxpayCallFaceService成功后务必调用此函数释放内存
 * @param pRespBuf	指向响应结果(JSON字符串)的指针
 */
extern "C" void wxpayReleaseResponse(char **pRespBuf);

# C# 导入DLL声明

// 声明
[DllImport("WxpayFaceSDK.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
public extern static int wxpayCallFaceService(IntPtr reqBuf, UInt32 reqSize, out IntPtr pRespBuf, out UInt32 pRespSize);

[DllImport("WxpayFaceSDK.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
public extern static int wxpayReleaseResponse(out IntPtr pRespBuf);

// 封装
public static int CallWxpayFaceService(string req, ref string resp)
{
    byte[] reqBuf = Encoding.UTF8.GetBytes(req);
    IntPtr reqPtr = Marshal.AllocHGlobal(reqBuf.Length);
    Marshal.Copy(reqBuf, 0, reqPtr, reqBuf.Length);

    IntPtr respPtr;
    UInt32 respSize;

    int ret = wxpayCallFaceService(reqPtr, (UInt32)reqBuf.Length, out respPtr, out respSize);
    if (ret == 0)
    {
        byte[] respBuf = new byte[respSize];
        Marshal.Copy(respPtr, respBuf, 0, (int)respSize);
        resp = Encoding.UTF8.GetString(respBuf);
        wxpayReleaseResponse(out respPtr);
    }
    Marshal.FreeHGlobal(reqPtr);
    return ret;
}

# 请求参数Req和响应结果Resp构成

req和resp均为JSON结构的字符串

req包含：公共请求字段 + 命令专有请求字段

resp 包含：公共响应字段 + 命令专有响应字段

# 请求公共字段

参数	必填	类型	说明
cmd	是	string	命令字，即各接口名： initWxpayface getWxpayfaceRawdata getWxpayfaceUserInfo releaseWxpayface
version	是	string	版本号, 固定填写1
now	是	int	取当前时间的10位unix时间戮。例如：1540901425

# 请求公共字段

参数	必填	类型	说明
return_code	是	string	错误码。公共定义见公共错误码
return_msg	是	string(128)	对错误码的描述

# 公共错误码

参数	错误码	类型	说明
return_code	SUCCESS	string	接口成功
return_code	ERROR	string	接口失败
return_code	PARAM_ERROR	string	参数错误
return_code	SYSTEMERROR	string	接口返回错误

# 接口调用流程

# 1、程序启动时初始化

# 程序启动时初始化initWxpayface

接口作用：对人脸SDK进行初始化

支持版本： 1.12及以上

# 请求参数

除公共参数外，下方参数中的代理设置可用于配置刷脸走商户内部代理。若不需要，则不用填写代理参数。

参数	必填	类型	说明
ip	否	string	HTTP代理IP
port	否	string	HTTP代理端口, 须为数字
user	否	string	HTTP代理的用户名
passwd	否	string	HTTP代理的密码
proxy_type	否	int	0:none; 1:HttpTunnel; 2:Socks5; 3:Http v1.18及以上支持
camera_rotation	否	int	对摄像头画面进行旋转，1为+90度，2为180度，3为-90度，如需使用该参数请联系微信支付确认设备实际效果符合规范。1.18版本以上支持

# 返回参数

参数	必填	类型	说明
return_code	是	string	错误码。公共定义见公共错误码
return_msg	是	string(128)	对错误码的描述

# 请求示例

// initWxpayface
// 初始化，默认无代理
const char* req = "{\"cmd\":\"initWxpayface\",\"version\":\"1\",\"now\":1540901425}";
// 初始化并配置代理
const char* req = "{\"cmd\":\"initWxpayface\",\"version\":\"1\",\"now\":1540901425,\"ip\":\"10.123.10.11\",\"port\":\"8356\",\"user\":\"username\",\"passwd\":\"password\"}";
char *resp;
unsigned int len;
int ret = wxpayCallFaceService(req, strlen(req), &resp, &len);

if (ret == 0) {
    printf("resp: %s len: %u\n", resp, len);
    wxpayReleaseResponse(&resp);
}
/*
 * resp: {"return_code":"SUCCESS","return_msg":"SUCCESS"} len: 48
 */

# 2、获取数据

# 获取数据getWxpayfaceRawdata

接口作用：获取rawdata数据

支持版本： 1.12及以上

# 请求参数

仅公共参数

# 返回参数

参数	必填	类型	说明
return_code	是	string	错误码。公共定义见公共错误码
return_msg	是	string(128)	对错误码的描述
rawdata	S	string(2048)	初始化数据。用于接口调用获取authinfo, 参见: 3、获取调用凭证

# 调用示例

// getWxpayfaceRawdata
const char* req = "{\"cmd\":\"getWxpayfaceRawdata\",\"version\":\"1\",\"now\":1540901425}";
char *resp;
unsigned int len;
int ret = wxpayCallFaceService(req, strlen(req), &resp, &len);

if (ret == 0) {
    printf("resp: %s len: %u\n", resp, len);
    wxpayReleaseResponse(&resp);
}
/*
 * resp: {"rawdata":"0CSmor/Pp4vC7WE5CsJxet4Sg+D24C8eJxAMjjkBEl58hDLmofPunD+OX8v7JQyxUFmimUb9ai9cuPmGXC87MfStCOGaK/Fjb77DzF7nJgpwQhl8bdprPWKx6h04ZzPRQBlE6DAgcylr3CFSisWpMSUUmA9MtHAKD8fhzFeTEAgj0NK49DjIFZXczfZRgj8qUTRrajdJtO6gZMqlRgSwM83MP8xPG2lCO33nA5HsSMy/vh5ET5O3ubj+wpfMuD1fUj3HBy3YXxxGqFKjJV6dRwuMmAXnaTk0P0u3LSOWO7wiA6En/JgwVZvf9zkcCzq9OyJFrc+8QY6bQeuPWCe4E73n397jaD5fu8GqyokUlO/XytuYP2qcNWAol9vBpf3u2xWt/MobKjJcsDwsCxGFxtjWATRyU0fB9atI8GKGt9zxwWbMd0m6gleWWVGVOHxodNKJbWFP4rRKvPjG0nntZzX4SJ0q/7zevKzYQhU+F+q+ePvvgjKAcxnI5Jhaz/khkffQLw4YAaR7GuLZhHYeFPYEvzOXVk89+dJ/M7s1jZK4dtFa75U1Et9vn2bYtfourPpL3PA9oPPVVu2gPuq/S+WmBG6hCp0lq+/3P4png82cgLq6MNPhSwAq5YRqxlrHbfE3qk0qr/vXXSMbIOhfLWnKFdOyRv+3ohdQOC/8sdHbbSDcyQSprYZ+JREhz0W3qPKlHxlsbvSrpGNj9D4VxL4UXTnloq5KdwZoGSeBgvpNS5NPhXuU6u0cVMufUriKsxptftFu68cDzVv3hdu+1bYy/P9vffwSl01U2uJiTGErHqVMuILTNL==","return_code":"SUCCESS","return_msg":"SUCCESS"} len: 885
 */

# 3、获取调用凭证

# 获取调用凭证get_wxpayface_authinfo(rawdata)（获取调用凭证）

接口作用：获取调用凭证

接口地址：https://payapp.weixin.qq.com/face/get_wxpayface_authinfo

# 请求参数

除公共参数外，下方参数的代理设置可用于配置刷脸走商户内部代理。若不需要，则不用填写。

参数	必填	类型	说明
store_id	是	string(32)	门店编号，由商户定义，各门店唯一。
store_name	是	string(128)	门店名称，由商户定义。（可用于展示）
device_id	是	string(32)	终端设备编号，由商户定义。
attach	否	string	附加字段。字段格式使用Json
rawdata	是	string(2048)	初始化数据。由微信人脸SDK的接口返回。获取方式参见： [获取数据 getWxpayfaceRawdata](#获取数据 getWxpayfaceRawdata) [获取数据 getWxpayfaceRawdata](#获取数据 getWxpayfaceRawdata)
appid	是	string(32)	商户号绑定的公众号/小程序 appid
mch_id	是	string(32)	商户号
sub_appid	否	string(32)	子商户绑定的公众号/小程序 appid(服务商模式)
sub_mch_id	否	string(32)	子商户号(服务商模式)
now	是	int	取当前时间，10位unix时间戳。例如：1239878956
version	是	string	版本号。固定为1
sign_type	是	string	签名类型，目前支持HMAC-SHA256和MD5，默认为MD5
nonce_str	是	string(32)	随机字符串，不长于32位
sign	是	string	参数签名。详见微信支付签名算法

# 返回参数

参数	必填	类型	说明
return_code	是	string(16)	错误码。公共定义见公共错误码
return_msg	是	string(128)	对错误码的描述
authinfo	是	string(4096)	SDK调用凭证。用于调用SDK的人脸识别接口。参见[人脸识别 getWxpayfaceCode](#人脸识别 getWxpayfaceCode)
expires_in	否	int	authinfo的有效时间, 单位秒。例如: 3600 在有效时间内, 对于同一台终端设备，相同的参数的前提下(如：相同的公众号、商户号、门店编号等），可以用同一个authinfo，多次调用SDK的`getWxpayfaceCode`接口。
nonce_str	是	string(32)	随机字符串
sign	是	string(32)	响应结果签名
appid	是	string(32)	公众号
mch_id	否	string(32)	商户号
sub_appid	否	string(32)	子商户公众账号ID(服务商模式)
sub_mch_id	是	string(32)	子商户号(服务商模式)

# 请求示例

<return_code>SUCCESS</return_code>
<return_msg>请求成功</return_msg>
<nonce_str>Tivppi4UXAbgLxk8e1Sij76YdowOFFii</nonce_str>
<sign>PL0EUID6A7ICWNKHCSMQC0UIXOYNSE5B</sign>
<appid>wx31fdaErqR31</appid>
<mch_id>12345689</mch_id>
<authinfo>q3OPhFtQBf6KZGqmZhejKCRy5K/ch0kwS11YSsEj9XmUGqcsT2QPHt0Oa7xaCMCoSZTWMmShCo4dOiO5tU+OJEsvSxXzn5m3Nkh747tinNlbpJmVq1zOPj+FJNndkzanxoiAddO8p1EfrmUhJs/aNf0pDfrPoVfkAapK+ZY6blwyaDQ9bB7+KkZq29kObsXOZ3thg+bxP4RAqC0oxNS4JiyP0uA1Euzxtkc9lCTebloFied8stILrMehUKukeMGkZ1SzTyc8/HFHApzHahNPX6yD8ttzYnhe+IRMFJgpuTlIvEOYZUxenPXE1A5clrPvOBeJDszX/OvZl4fpYWPpXAcVQlw+gfYhblt+rT6ALMsD73w/rT4NRriQEEraC4Pfb5yua4qAqv4TVo04</authinfo>
<expires_in>7200</expires_in>

建议：返回的接口凭证authinfo，可以在expires_in指定的有效期内，同一台机具上重复使用

注意：这是一个后端调用接口,请在获取数据(getWxpayfaceRawdata)成功后获取调用凭证get_wxpayface_authinfo(rawdata)

# 4、获取用户信息

# 获取用户信息getWxpayfaceUserInfo（authinfo）

接口作用：通过人脸识别获取用户信息，包括openid，昵称、unionid等信息。

**适用范围：**适用于会员、推荐等场景。

支持版本： 1.24及以上

# 请求参数

除公共参数外，

参数	必填	类型	说明
appid	是	string	商户号绑定的公众号/小程序 appid
mch_id	是	string	商户号
sub_appid	否	string(32)	子商户绑定的公众号/小程序 appid(可不填)
sub_mch_id	否	string(32)	子商户号(非服务商模式不填)
store_id	是	string	门店编号
face_authtype	是	string	人脸识别模式。可选值： `FACEID-ONCE`: 人脸识别(单次模式)
authinfo	是	string	调用凭证。获取方式参见: [获取调用凭证后端接口](### 获取调用凭证后端接口)
ask_unionid	否	string	是否请求获取union_id。可选值 [0:不获取;1:获取]
screen_index	否	string	指定刷脸界面显示的屏幕编号。编号1为主屏幕，其余屏幕按系统设置中的顺序从2开始编号，常用场景举例：双屏机器上传"2"即可显示在副屏上。如果不填写则默认显示在主屏幕。
use_window_nofocus	否	string	设置刷脸窗口以无焦点方式启动，可选值："1"，无焦点启动窗口。1.26版本以上支持该参数

# 返回参数

参数	必填	类型	说明
return_code	是	string	错误码。公共定义见公共错误码
return_msg	是	string(128)	对错误码的描述
openid	是	string	openid
sub_openid	否	string	子商户号下的openid(服务商模式)
nickname	是	string	微信昵称
token	否	string	用于获取union_id，获取union_id文档
unionid_code	否	string	获取union_id 返回码。公共定义见公共错误码
unionid_msg	否	string	获取union_id 返回信息，对unionid_code返回码的描述

# 请求示例

// getWxpayfaceUserInfo
const char* req = "{\"cmd\":\"getWxpayfaceUserInfo\",\"appid\":\"wx2b029c08a6232582\",\"mch_id\":\"1900008001\",\"store_id\":\"DemoStore\",\"face_authtype\":\"FACEID-ONCE\",\"authinfo\":\"YNrFgiTFMBgJhON9HbkOeL/oYeg2CqpbsYAIuzB7i3iio2YGuZhFMe+H5G7yO+wpHHRiAKGo335ZWWeckRK/5uSF+o9oXsdyroMoTD9uhP+L8hzuqWxz464DsaWpL1xc0Rn4Smaxv9/pvCL8PfYxG7L2J1zhqAH0Wrsi3h2QMHA5/jsTfXqNz8nvBvjSq3hmTazytkafVaaxFKf3ZDHqWq+9DSepqsGIUPzHWxFZQ/k378H7d/PpPXpKKYSp6oPwixFXujZLDgDzjIE4//ORHnFmr9Dr8LF2y4Iqb2NcZnKBNPFuiqhcOOk70BTY2ggr6M6tsZEJkIIWH0XnrDH6pmcJntxQDAdaEvm1tZoCX7vUK0rkFJ1axeMZXVskfueaCaCMTAjjfGjTHBaMWTvrBP85tteZ+aXwvcWkVg9g/VMyo3wzV1PlU1iYNhaMfoieiXhJnRpOwqVKseIINBzXqEzg3PHTB3p/AFZ2gxcwOKJa0wbxM5QWzeplPTkPgJhM7SfDSet/ZOMb7MCzoB4MT0P3dYGf3s3/LaGZ2gqMU0MOCs85kb3jNIsUpm0v3xd4+juQsfdUX2309Kh2HGEgPcUWLUMEdj5AfJLh9x/8wbx7aEwTTpBP6KgtZrjBobOZnxT5CyVbR0s4uUIqQlz9zuiOI+V80hAbBqg88G/YHUJKgr7Hv9Fwqj6P4aTytWPrrKkG3HkO\",\"version\":\"1\",\"now\":1598426587}";
char *resp;
unsigned int len;
int ret = wxpayCallFaceService(req, strlen(req), &resp, &len);

if (ret == 0) {
    printf("resp: %s len: %u\n", resp, len);
    wxpayReleaseResponse(&resp);
}
/*
 * resp: {"return_code":"SUCCESS","return_msg":"SUCCESS","openid":"xxx","nickname":"xxxx"} len: 48
 */

注意：请在获取调用凭证get_wxpayface_authinfo(rawdata)成功后调用获取用户信息getWxpayfaceUserInfo（authinfo）

# 5、释放资源

# 释放资源releaseWxpayface

接口作用：释放人脸服务。

接口使用规范：

聚合支付情况下：每次启动刷脸都需要initWxpayface，刷脸结束后需要调用releaseWxpayface（释放摄像头供其他刷脸支付平台调用）；
非聚合支付情况下：首次刷脸需要initWxpayface，刷脸结束后不需要调用releaseWxpayface，否则下次刷脸需要重新initWxpayface，影响启动耗时；初始化之后第二次刷脸可以直接调用getWxpayfaceCode启动刷脸（在保证authinfo有效的情况下）。

支持版本： 1.12及以上

# 请求参数

仅公共参数

# 返回参数

参数	必填	类型	说明
return_code	是	string	错误码。公共定义见公共错误码
return_msg	是	string(128)	对错误码的描述

# 请求示例

// releaseWxpayface
const char* req = "{\"cmd\":\"releaseWxpayface\",\"version\":\"1\",\"now\":1540901425}";
char *resp;
unsigned int len;
int ret = wxpayCallFaceService(req, strlen(req), &resp, &len);

if (ret == 0) {
    printf("resp: %s len: %u\n", resp, len);
    wxpayReleaseResponse(&resp);
}
/*
 * resp: {"return_code":"SUCCESS","return_msg":"SUCCESS"} len: 48
 */