关闭
公众号二维码
刷脸支付

# 离线刷脸开发接入注意事项

# 1. [终端]离线刷脸SDK API调用注意事项

# 1.1 兼容人脸服务中断的情况（看门狗机制）

人脸应用升级时，需重新安装，触发人脸进程重启，从而导致服务中断。
建议：

  1. 人脸应用OTA升级时，ROM不要拉起人脸应用到前台；
  2. 主动感知服务断连，如：门禁长时间无回调，接口调用无返回等。

影响：
团餐场景，当次刷脸体验中断，重试可恢复；
门禁场景，连续识别，如果未感知到人脸服务销毁，将导致业务中断。

# 1.2 避免频繁销毁初始化人脸服务：initWxpayface/releaseWxpayface

注意事项

  1. 初始化时机：建议在应用启动时初始化。
    自定义商户应用Application，在Application#onCreate()中调用initWxpayface。
    影响：
    若等到使用才初始化，会导致第一次刷脸体验缓慢。

  2. Context建议使用ApplicationContext，应用存活期间，保持人脸服务连接。
    影响：
    如果使用Activity/Service作为context传入，需要处理结合组件生命周期init/release人脸服务来处理内存泄漏问题。

  3. 尽量不要调用releaseWxpayface，release接口会销毁人脸服务，给下次初始化带来不必要耗时。
    影响：
    a、release会导致人脸服务断连，再连接需要耗时；
    b、频繁init/release，会导致刷脸体验缓慢/卡顿。

# 1.3 有效期内请缓存复用AuthInfo

注意事项

  1. authInfo具有时效性 "expires_in"字段 （默认3600，即1小时），在有效期内，商户不需要重复请求，建议商户对authInfo进行缓存，每1小时进行更新。
    影响：如果每次刷脸都请求authInfo，引入不必要的网络耗时，会导致刷脸体验缓慢/卡顿。

# 1.4 及时更新人脸特征库：manualUpdateFaceDatas/getSdkInfo

注意事项

  1. 建议商户APP在人脸服务初始化完成后，尽快调用接口更新人脸数据。首次识别前，要求进行一次特征更新（成功/失败都可以），更新过程中，禁止用户操作，等待回调再开始操作。
  2. 人脸服务会定时自动触发特征更新（90s/次），但不会触发回调。
  3. getSdkInfo 可以获取最近一次更新时间，字段key为：“last_update_data_time”，服务商可定期自查上次更新时间，如果超过10分钟没更新，可能设备网络出现异常，请及时处理。
    影响：
    如果不及时更新将影响业务可用性，刚录入的新同学将无法识别，解约的旧同学可能还能继续识别。

# 1.5 预加载/预打开摄像头：preloadSdkEnv

注意事项

  1. 摄像头启动、人脸特征加载会有一定耗时，提前preloadsdkenv加载资源，可以保证第一次开启摄像头和识别启动很快；
    影响：一般场景下，只有首次刷脸打开摄像头会比较慢。
    VoIP场景/聚合支付：如果摄像头释放了，再次重新打开需1～2s，会导致刷脸缓慢。

# 1.6 设置刷脸预览：setCameaPreview

注意事项

  1. surface不能为空，surface销毁后需要重新绑定；
  2. surfaceView推荐全局使用同一个实例；
  3. 绑定最佳时机为surfaceview不会再发生大小改变或者隐藏的时刻，避免需要动态适配；
  4. 默认画面为480x640，没有比例限制，推荐按照3:4的长宽比显示，从而扩大预览范围，方便适配竖版摄像头，避免不同身高用户需要弯腰垫脚；
  5. 尽量在surfaceview大小确定以后再进行调度，避免出现时序不当问题。
    影响：
    销毁未重绑定/绑定后不断改变大小导致时序不当，可能导致surface渲染白屏。

# 1.7 刷脸识别流程：startVerify/stopVerify/finishFaceVerify/getFacePayCredential

注意事项

  1. 接口分为开始/停止，识别成功后自动停止，而识别失败会返回错误码并且自动重新开始识别，建议自行设置最长超时实践，推荐40s；
  2. 识别成功返回的userInfo类型，需要防止混淆，在proguard里需要keep对应的class。
-keep class com.tencent.wxpayface.data.UserInfo{ *; }；
  1. startFaceVerify 调用前必须更新人脸特征数据；
  2. 识别成功后注意判断“need_ext_verify”字段，确认是否需要辅助验证。

时序要求

  1. 正常支付流程，需要以获取支付凭证(getFacePayCredential)作为支付标准终点；
  2. 异常支付流程（取消/失败），请不要调用(getFacePayCredential)，以免干扰支付侧流失率统计。
    影响：调用不规范会导致支付告警误报，无法更好的帮助商户提升刷脸体验。

错误案例
● 没有得到识别回调就调用finishFaceVerify，此时流程报错“没有用户信息”，等到识别回调成功后，再次调用finishFaceVerify->getFacePayCredential，此时支付流程正常。
分析：第一次报错，支付侧会认为用户刷脸失败，用户流失。
实际上用户可以正常支付。

● 没有调用finishFaceVerify时，就调用getFacePayCredential，此时报错“userId 为空”。后面调用正确，此时支付流程正常。
分析：第一次报错，支付侧会认为用户刷脸失败，用户流失。
实际上用户可以正常支付。

流程参考

标准时序：
startFaceVerify -> 识别回调 -> (辅助验证) -> finishFaceVerify -> getFacePayCredential

中断逻辑：
stopFaceVerify 仅停止渲染及识别，不会清除识别数据，支持任意时刻调用，停止之后请勿继续调用。

# 1.8 定期重启机制

为避免设备运行时间过长导致突发异常，建议非高峰期定期重启，推荐1～3点，凌晨1点前作为升级时间。

影响：长时间不重启，担心商户APP/人脸服务/系统/摄像头等多因素出现未知异常。

# 2. [后端]离线刷脸商户接入常用接口调用注意事项

# 2.1 获取凭证授权接口

POST https://api.mch.weixin.qq.com/v3/offlinefacemch/tokens

注意事项：
指定银行卡签约，用户签约时携带的token请使用预签约接口获取，该接口不支持指定卡签约。

# 2.2 刷脸用户信息修改接口

PATCH https://api.mch.weixin.qq.com/v3/offlinefacemch/organizations/{organization_id}/users/out-user-id/{out_user_id}

注意事项：
若修改了学生姓名、班级、手机号时，需调用接口同步给微信侧，否则可能导致小助手上记录欠款的学生姓名、班级与实际不符合以及学生刷脸验证手机号时无法通过。

# 2.3 获取authinfo接口

POST https://api.mch.weixin.qq.com/v3/offlineface/authinfo

注意事项：
建议authinfo每1小时内获取一次，否则当设备断网且恰好authinfo过期，则会导致设备不可用。
请求参数机构ID字段，创建机构的商户号和mch_id应该保持一致，否则无法获取authinfo。

# 2.4 预签约接口

POST https://api.mch.weixin.qq.com/v3/offlineface/contracts/presign

注意事项：

  1. 一键绑卡不是支持所有银行卡，上线前请先测试是否支持该银行卡；
  2. 建议上线前一周完成调试；
  3. 签约完成务必多次扣款，防止由于银行限制每日扣款次数、扣款金额等影响用户消费；
  4. 指定卡签约建议异步扣款，否则银行维护会导致不能扣费，影响学生吃饭。

# 2.5 申请扣款接口

POST https://api.mch.weixin.qq.com/v3/offlineface/transactions

注意事项：
返回码处理建议

httpcode 错误码 处理方式
200 请求正确处理，应该判断订单状态 “SUCCESS”-支付成功（支付成功无需处理）
“REFUND"-转入退款（支付成功无需处理）
“NOTPAY”-未支付（24小时内参数不变重试扣款）
“CLOSED"-已关闭（参数不变换单号重试）
“REVOKED”-已撤销（参数不变换单号重试）
“USERPAYING”-用户支付中（24小时内参数不变重试扣款）
“PAYERROR”-支付失败(换单号重试)
500 SYSTEM_ERROR 请稍后重试，建议同一笔订单每天重试不要超过5次，频繁重试会导致该用户无法扣款
400 PARAM_ERROR 参数错误，请检查参数
400 INVALID_REQUEST 目前子商户未开通权限、凭证已经使用过并且扣款成功、请求参数和凭证信息不一致、凭证正在扣款又换单号重试、重入请求变更了参数都会返回该错误码，表示请求参数符合格式，但不符合业务规则，需要服务商定位问题并修正代码
429 RATELIMIT_EXCEEDED 请求达到速率限制

# 2.6 其他

out_user_id：刷脸用户标识，需要商户保证同一个刷脸用户在一个机构下唯一, 不要给同一个用户创建多个out_user_id, 否则用户会无法使用(即便前一个已经解约也不行)。

上次更新: 11/14/2022, 3:01:17 PM