NFC for Document report
Start here
Recent passports, national identity cards and residence permits contain a chip that can be accessed using Near Field Communication (NFC). The Onfido SDKs provide a set of screens and functionalities to extract this information, verify its authenticity and provide the resulting verification as part of a Document report.
NFC is available via Onfido's iOS and Android SDKs.
Follow this guide to:
- Configure NFC with Onfido Studio
- Use NFC directly with the Onfido SDKs
- Interpret the verification results in a Document report
You can view the list of currently supported documents for NFC.
Please contact your Customer Success manager for additional help with integrating NFC.
Using NFC
NFC in Onfido Studio
It is recommended to enable and manage NFC in Onfido Studio.
In Studio, NFC extraction is controlled by a single toggle within the Document Capture task:
With NFC enabled:
- Studio will instruct the Onfido SDKs to prompt users to scan their document via NFC (if both the document and the device are NFC capable)
- Users with NFC-enabled documents will be asked to scan their document and can only skip NFC scanning after 5 failed attempts
- If a user selects a document without NFC, they will not be asked to scan NFC
- Document report tasks linked to this task will automatically generate the
issuing_authority
breakdown detailing the NFC verification steps - Any subsequent Facial Similarity tasks will use the applicant's picture present in the NFC chip by default for comparison
Configuring NFC in the Onfido SDKs
NFC extraction is enabled by default since the release of the following Onfido SDK versions:
SDK | Version | Technical Documentation |
---|---|---|
iOS | 29.1.0 | ios SDK reference |
Android | 18.1.0 | Android SDK reference |
React Native | 9.0.0 | React Native SDK reference |
Flutter | 4.0.0 | Flutter SDK reference |
Please refer to the relevant instructions for the detailed steps on how to declare the necessary dependencies and permissions in your application.
To activate NFC in older SDK versions, please refer to the corresponding SDK version's technical reference.
NFC results in the Document Report
Upgrade to API v3.2+
You must upgrade your backend to use API v3.2 or later in order to receive the issuing_authority
breakdown and sub-breakdowns that contain the details of the NFC verification in the Document report.
- if you are currently using API v2 please see this migration guide
- if you are currently using API v3 please see this migraton guide
NFC is not available in earlier versions of the Onfido API. Please refer to our API versioning policy.
Create a check containing a Document report with NFC
Once you have enabled NFC in the Onfido SDK and upgraded to API v3.2 or later, you can create a check containing a Document report with NFC.
Start the SDK flow
The SDK flow for a Document report with NFC includes both the standard document step capture screens and additional NFC scan screens.
All users will first be presented with the document capture screens. The additional NFC screens will then be presented to the user if both the user's device and the document type support NFC. Otherwise, the user will finish the SDK flow after the document capture step and no NFC scan will be completed.
Document IDs
On success the SDK will return a callback which contains an array of document IDs. The document IDs will include:
- the document front image
- the document back image (if the document has 2 sides, for example an ID card)
- the NFC media (if the document is supported for NFC and an NFC scan has completed successfully)
You need to extract all the document IDs to use when creating a check on the backend.
iOS
func getDocumentIds(fromResults results: [OnfidoResult]) -> [String]? {
return results.map({ onfidoResult -> [String] in
switch onfidoResult {
case .document(let documentResult):
guard let nfcMediaId = documentResult.nfcMediaId else {
return []
}
var ids: [String] = [documentResult.front.id]
if let backId = documentResult.back?.id {
ids.append(backId)
}
ids.append(nfcMediaId)
return ids
default:
return []
}
}).first
}
OnfidoFlow(...)
.with(responseHandler: { response in
switch response {
case .success(let results):
if let documentIds = getDocumentIds(fromResults: results) {
// USE DOCUMENT IDS FOR CHECK CREATION
}
...
}
})
(NSArray<NSString*>*)getDocumentIds:(NSArray *)flowResults {
ONFlowResult *flowResult = [flowResults firstObject];
if (flowResult.type == ONFlowResultTypeDocument) {
ONDocumentResult *documentResult = (ONDocumentResult *)flowResult.result;
NSMutableArray *documentIds = [NSMutableArray new];
[documentIds addObject:documentResult.front.id];
if (documentResult.nfcMediaId != nil) {
[documentIds addObject:documentResult.nfcMediaId];
}
if (documentResult.back != nil) {
[documentIds addObject:documentResult.back.id];
}
return [NSArray arrayWithArray:documentIds];
}
return @[];
}
ONFlow *flow = [[ONFlow alloc] initWithFlowConfiguration:config];
[flow withResponseHandler:^(ONFlowResponse *response) {
if (flowResponse.results) {
NSArray *documentIds = [self getDocumentIds:flowResponse.results];
// Use document IDs for check creation
} else if (flowResponse.error) {
// Handle Error
} else if (flowResponse.userCanceled) {
// Handle User Canceled Action
}
}, dismissFlowOnCompletion: /* Dismiss Completion Here */ ];
Android
override fun userCompleted(captures: Captures) {
val documentIds = captures.toJson()
// add the document ids to check creation request body
add("document_ids", documentIds)
}
private fun Captures.toJson(): JsonArray {
val array = JsonArray()
document?.nfcMediaUUID?.let { uuid -> array.add(uuid) }
document?.front?.let { frontSide -> array.add(frontSide.id) }
document?.back?.let { backSide -> array.add(backSide.id) }
return array
}
oid userCompleted(@NonNull Captures captures) {
JsonArray jsonCaptures = capturesToJson(captures);
// add the document ids to check creation request body
JsonObject requestBody = new JsonObject();
requestBody.add("document_ids", jsonCaptures);
}
JsonArray capturesToJson(@NonNull Captures captures) {
JsonArray array = new JsonArray();
if (captures != null) {
Document document = captures.getDocument();
if (document != null) {
String nfcMediaUUID = document.getNfcMediaUUID();
if (nfcMediaUUID != null) {
array.add(nfcMediaUUID);
}
DocumentSide frontSide = document.getFront();
if (frontSide != null) {
array.add(frontSide.getId());
}
DocumentSide backSide = document.getFront();
if (backSide != null) {
array.add(backSide.getId());
}
}
}
return array;
}
React Native
Onfido.start({
sdkToken: 'sdkTokenFromOnfidoServer',
flowSteps: {
welcome: true,
captureFace: {
type: OnfidoCaptureType.VIDEO,
},
captureDocument: {
docType: OnfidoDocumentType.DRIVING_LICENCE,
countryCode: OnfidoCountryCode.USA,
}
},
})
.then(res =>
const result = JSON.stringify(res);
const nfcMediaId = result.document.nfcMediaId ?? result.document.nfcMediaUUID;
const frontId = result.document.front.id;
const backId = result.document.back.id;
)
.catch(err => console.warn('OnfidoSDK: Error:', err.code, err.message));
Flutter
private var result: MethodChannel.Result? = null
override fun userCompleted(captures: Captures) {
// deserialize the received captures as per your needs, for example:
result?.success(captures.toFlutterResult())
result = null
}
internal fun Captures.toFlutterResult(): Any {
val elements = mutableMapOf<String, Any>()
this.document?.let {
elements["document"] = it.deserialize()
}
this.face?.let {
elements["face"] = it.deserialize()
}
return listOf(elements)
}
private fun Face.deserialize(): Map<*, *> {
return mapOf("id" to id, "variant" to this.variant.ordinal)
}
private fun Document.deserialize(): Map<*, *> {
val map = mutableMapOf<String, Any>()
map["typeSelected"] = this.type.toString().lowercase()
map["nfcMediaId"] = this.nfcMediaUUID.toString()
front?.let {
map["front"] = mapOf("id" to it.id)
}
back?.let {
map["back"] = mapOf("id" to it.id)
}
return map
}
Create a check
On success, create a check on your backend.
Example for an NFC supported passport:
curl -X POST https://api.eu.onfido.com/v3.2/checks \
-H 'Authorization: Token token=<YOUR_API_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"applicant_id": "<APPLICANT_ID>",
"report_names": ["document"],
"document_ids": ["<DOCUMENT_ID_FRONT>", "<NFC_MEDIA_ID>"]
}'
Parameter | Notes |
---|---|
applicant_id (required) |
Specifies the applicant for the check. |
report_names (required) |
The report name. NFC is available as part of the primary Document report option. |
document_ids (required) |
Array including all the document IDs returned in the SDK success callback. This could include up to 3 IDs for the document front side, back side and NFC media. |
Note: document_ids
is only a required parameter for a Document report with NFC as you need to specify the NFC media ID at check creation. For a standard Document report, document_ids
is an optional parameter.
For more details on how to create a check, see our quick start guide.
Result handling
Report breakdown
The issuing_authority
breakdown captures the result of the NFC scan. It asserts whether data on the document matches the issuing authority data and uses the following sub-breakdowns:
nfc_passive_authentication
- asserts the data integrity of the NFC datanfc_active_authentication
- asserts whether the document NFC chip is original or cloned
Result logic
Passive Authentication and Active Authentication are checked whenever supported by the underlying document. Each check can return a result of clear
, consider
or null
as below:
nfc_passive_authentication |
nfc_active_authentication |
|
---|---|---|
Not supported by document | null |
null |
Unable to read data | null |
null |
Failed | consider |
consider |
Succeeded | clear |
clear |
The individual results are then combined in the issuing_authority
breakdown into a single result:
nfc_active_authentication is null |
nfc_active_authentication is consider |
nfc_active_authentication is clear |
|
---|---|---|---|
nfc_passive_authentication is null |
null |
consider |
clear |
nfc_passive_authentication is consider |
consider |
consider |
consider |
nfc_passive_authentication is clear |
clear |
consider |
clear |
The overall document verification result is influenced by the issuing_authority
breakdown as follows.
Note that if fallback to Visual checks is disabled, the Issuing Authority section would be the main driver to the overall result.
Issuing Authority Breakdown | Overall Document Verification |
---|---|
null |
rejected |
consider |
suspected |
clear |
clear |
Note that if the document's NFC data contains the applicant's photograph, this photograph will be used in any subsequent facial similarity checks, if configured.
Configuration options
In addition to the NFC verification described in this document, you can configure your account to also trigger Visual Document Verification whatever the issuing_authority
breakdown result (clear
, consider
or null
). In those cases, the visual authentication, image integrity and data consistency checks will be performed and the results returned in the respective report breakdowns.
Please contact your Customer Success manager to enable this.
Properties
In the Document check properties an nfc
object is returned which includes the NFC extracted document data.
If NFC is not available, no data will be extracted and the nfc
object will not be returned.
Addendum
Disabling NFC and Removing SDK dependencies
As NFC is enabled by default and library dependencies are included in the build automatically, the following section details the steps required to disable NFC and remove any libraries from the build process.
iOS
- Disable
Near Field Communication Tag Reading
capability in your app target. You can follow the steps in Apple's documentation - Remove any entries relating to the NFC setup from your app target's
Info.plist
file (please refer to the iOS SDK documentation) - Pass the following method to disable NFC in the iOS SDK.
let config = try! OnfidoConfig.builder()
.withSDKToken("<YOUR_SDK_TOKEN_HERE>")
.withDocumentStep()
.disableNFC()
.build()
ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder];
[configBuilder withSdkToken:@"YOUR_SDK_TOKEN_HERE"];
[configBuilder withDocumentStep];
[configBuilder disableNFC];
NSError *configError = NULL;
ONFlowConfig *config = [configBuilder buildAndReturnError:&configError];
Android
- Remove any dependencies (with the specified versions) relating to NFC from your build script. Please refer to the Android SDK documentation
- Pass the following method to remove the NFC document extraction step from the Android SDK flow.
val config = OnfidoConfig.builder(this@MainActivity)
.withSDKToken(“<YOUR_SDK_TOKEN_HERE>”)
.disableNFC()
.withCustomFlow(flowSteps)
.build()
OnfidoConfig config = OnfidoConfig.builder(context)
.withSDKToken(“<YOUR_SDK_TOKEN_HERE>”)
.disableNFC()
.withCustomFlow(flowSteps)
.build()
React Native
- Remove any dependencies relating to NFC. Please refer to the readme file
- Include the following initialisation option to remove the NFC document extraction step from the React Native SDK flow.
config = {
sdkToken: “<YOUR_SDK_TOKEN_HERE>”,
flowSteps: {
<YOUR_FLOW_STEPS_CONFIGURATION_HERE>
},
disableNFC: true
}
Flutter
- Remove any dependencies relating to NFC. Please refer to the readme file
- Include the following initialisation option to remove the NFC document extraction step from the Flutter SDK flow.
config = {
sdkToken: “<YOUR_SDK_TOKEN_HERE>”,
flowSteps: {
<YOUR_FLOW_STEPS_CONFIGURATION_HERE>
},
disableNFC: true
}