Only the Chinese version of this page is provided currently. The English version will be provided soon.

微信小程序接入指引

Last updated: 2026-05-25 12:13:07

接入流程

1. 下载 NFC 小程序 SDK,并在小程序代码中引入,调用 init 方法进行初始化。
2. 接入方服务端调用 GetNFCToken 接口,获取到 NFC 核验流程标识(BizToken)。
3. 客户后端将 BizToken 返回给客户小程序端,然后小程序调用 wx.startNfcVerify() 进入 NFC 身份证件核验流程。
4. 用户完成 NFC 读卡核验后,会以回调函数形式返回 BizToken,接入方小程序将 BizToken 传给接入方服务端,接入方服务端即可凭借 BizToken 参数调用 GetWxNFCResult 接口获取本次核验的详细信息。

SDK 接入

开发准备

环境要求

项目
说明
终端
仅 Android(iOS 小程序不支持 NFC,SDK 会返回 ErrorCode: -201)
微信版本
建议 8.0.0 及以上
硬件
设备需支持 NFC 且处于开启状态

下载 SDK

下载 NFC 小程序 SDK。

安装 SDK

nfc_sdk 文件夹放在小程序根目录下,使用 require 函数引入。
const Verify = require('/nfc_sdk/main');

调试 SDK

请在微信开发者工具中使用手机"预览"模式进行调试,请勿使用"真机调试"。NFC 读卡功能需在 Android 真机上测试。

卸载 SDK

卸载时删除 nfc_sdk 文件夹,移除相应 require 代码即可。

快速入门

1. nfc_sdk 文件夹放到小程序项目根目录。
2. 初始化 NFC SDK。
app.jsonLaunch() 中加入相应代码,在 app.json 文件里添加 NFC 验证页面 nfc_sdk/index/index
// app.js
App({
onLaunch: function () {
// 初始化 NFC SDK
const Verify = require('/nfc_sdk/main');
Verify.init();
}
})
// app.json
{
"pages": [
"nfc_sdk/index/index"
]
}
3. 调用 SDK 功能函数 wx.startNfcVerify()
在需要 NFC 身份核验的地方调用 wx.startNfcVerify() 进入核验流程,核验完成会触发对应的回调函数。
身份证类(默认):
gotoVerify: function () {
let BizToken = getBizToken(); // 客户自定义函数,从后端获取 Token
wx.startNfcVerify({
data: {
token: BizToken, // 必填,来自 GetNFCToken
cardType: '01', // 可选,证件类型 code,默认 '01' 身份证
},
success: (res) => { // 验证成功后触发
// res.BizToken 为本次验证对应的 Token
setTimeout(() => {
// 验证成功后的逻辑处理
}, 500);
},
fail: (err) => { // 验证失败时触发
// err.ErrorCode 错误码,err.ErrorMsg 错误信息
setTimeout(() => {
wx.showModal({
title: "提示",
content: err.ErrorMsg,
showCancel: false
})
}, 500);
}
});
}
旅行证类(需额外传入三要素):
gotoVerify: function () {
let BizToken = getBizToken();
wx.startNfcVerify({
data: {
token: BizToken,
cardType: '06', // 证件类型,如港澳通行证
cardNumber: 'C12345678', // 证件号码
birthday: '910323', // 出生日期,6 位 YYMMDD
expriyDay: '270320', // 有效期,6 位 YYMMDD
},
success: (res) => {
setTimeout(() => {
// 验证成功后的逻辑处理
}, 500);
},
fail: (err) => {
setTimeout(() => {
wx.showModal({
title: "提示",
content: err.ErrorMsg,
showCancel: false
})
}, 500);
}
});
}
4. 添加域名服务器白名单。
您需要在小程序上线前进入:微信公众号管理平台 > 管理 > 开发管理 > 开发设置 > 服务器域名中将以下域名添加至白名单,小程序前端接口请求有域名白名单限制,未添加白名单的域名只能在调试模式下运行。
// request 合法域名
nfc.faceid.qq.com,faceid.qq.com

基本 API 描述

Verify.init()

初始化 NFC SDK,需在 app.jsonLaunch() 中调用。

wx.startNfcVerify(options)

进入 NFC 身份证件核验页面。
options 参数说明:
参数
类型
必填
说明
options.data.token
String
客户后端调用 GetNFCToken 接口获取的 BizToken
options.data.cardType
String
证件类型 code,默认为 '01'(身份证),详见下方证件类型表
options.data.cardNumber
String
旅行证类必填
证件号码
options.data.birthday
String
旅行证类必填
出生日期,6 位数字 YYMMDD 格式
options.data.expriyDay
String
旅行证类必填
有效期,6 位数字 YYMMDD 格式
options.success
Function(res)
验证成功的回调,res.BizToken 为本次验证的 Token
options.fail
Function(err)
验证失败的回调,err.ErrorCode 为错误码,err.ErrorMsg 为错误信息
cardType 证件类型取值:
身份证类(只需传 token):
cardType
证件名称
01(默认)
身份证
13
外国人永久居留证
14
港澳台居民居住证
旅行证类(需额外传入 cardNumber / birthday / expriyDay):
cardType
证件名称
06
港澳通行证
07
台胞证
08
外国护照
15
回乡证
16
大陆居民来往台湾通行证
注意:
传入不支持的 cardType 会自动兜底为身份证(01)。

错误码

ErrorCode
含义
0
成功
-1
用户退出 NFC 验证
-100
token 为空
-101
旅行证类三要素(cardNumber / birthday / expriyDay)缺失
-104
网络请求失败
-201
设备不支持 NFC / NFC 未开启 / iOS 机型
-202
跳转 NFC 验证页面失败
-203
获取 NFC 配置失败
说明:
业务层错误码(TriggerDecode 返回)透传自服务端,具体含义以慧眼服务端文档为准。

操作步骤

步骤1:获取 Token

接入方服务端调用腾讯云 API GetNFCToken 获取 BizToken,用于发起本次 NFC 核验流程。
注意:
BizToken 仅对应一次核验流程,有效时间为 600 秒;用户完成核验后,开发者可用该标识获取验证结果信息,结果信息仅保留 7 天。

步骤2:调用 SDK 发起核验

客户后端将 BizToken 下发给小程序端后,调用 wx.startNfcVerify() 发起 NFC 核验流程,用户进入核验页面完成 NFC 读卡操作。

步骤3:查询核验结果

用户完成 NFC 核验后,success 回调会返回 BizToken。接入方将 BizToken 传给服务端,服务端调用 GetWxNFCResult 接口获取本次核验的详细信息。
注意:
在开发、产品使用、费用、合同等问题有任何疑问,欢迎您 联系我们 进行询问。