¶ Getting Started
Thank you for visiting this site. The NIMC is here to help guide you through the steps to become fully compliant with the new regulations regarding Data Privacy using Tokenization of the NIN.
¶ New Verification Applicants
If you are requesting credentials to start, please visit https://ent.nimc.gov.ng to kick the ball rolling.
¶ Existing Licensed Verification Agents
If you are an existing licensed verification partner with the NIMC (and have VPN access to the NIMC services), please contact Mr. Kayode Aina, Project Management Office (kayode.aina@nimc.gov.ng) to obtain your access credentials to the new Enterprise Credentials package, which will include:
- Public & Private Keys (not to be shared)
- Super Administrator Credentials
- AES Encryption Key (definitely not to be shared)
The portal allows you to toggle seamlessly between test and production as required.
An email will be sent directly to the named contact for your enterprise, made available at NIMC. If that person is no longer in your employ, you may wish to first update your approved contact information at NIMC.
After the cutover date, access to the existing Verification Service will be highly restricted and no longer available for RAW NIN Verification.
¶ Production Credentials
As a new enterprise, once you have completed the integration testing, the next step is to issue the Production Credentials. Please have your ICT team/developers confirm the following:
- Have you completed your Integration Testing using the Test Credentials?
(a) You confirm you can request to verify a Virtual NIN and it returns and encrypted payload
(b) You can use your Private Key to decrypt the payload in (a) above - You are now requesting Production Credentials.
If the answers to the questions above are in the affirmative, please send an email to Kayode.aina@nimc.gov.ng and copy Chinenye.chizea@nimc.gov.ng to request for production credentials.
Please be advised that the NIN Tokenization project of the Federal Government of Nigeria IS NOT limited to the Virtual NIN as described below. It also includes the:
- Improved NIN Slip (ninhash)
- WalletID (for Fintech Mobile App KYC integration)
- UserID (masked NIN)
- MobileID (basic and full ID Hashes)
For further information, please click here.
¶ QR Code for MobileID Virtual NIN Issuance
The Virtual NIN issuance process is to provide the ID Holder a simple, yet secure means for the person to issue a token to a Relying Party (the verifying enterprise).
¶ Role of the vNIN Issuer
This process requires the ID Holder (known as the Issuer) to do the following:
- Ensure they have downloaded and onboarded themselves on the NIMC MobileID application
- Log into the MobileID app and click on the “Get Virtual NIN” button
- Point the camera on the device to your QR Code (displayed in a rollup banner or other visible presentation medium)
- Wait for a maximum of 2-3 seconds for the Virtual NIN to be issued and displayed on their device
- Present the token to the agent of the Relying Party
¶ Role of the Relying Party
The Relying Party (or verifier in other parlance), is expected to seek and obtain User Consent, as defined by the Federal Government of Nigeria, to enable them carry out a verification of the Virtual NIN.
To this end, the Relying Party is expected to do the following:
- Present guidelines for the ID Holder (known as the Issuer), to be able to download the NIMC MobileID application (if they are yet to do so)
- Ask the Issuer to log into the app (using their previously setup log in PIN) and click on the “Get Virtual NIN” button
- Ask the Issuer to point the camera of their device to the Rollup banner (or other clearly-visible medium) containing the QR code for VNIN issuance
- Request for the VNIN that was issued by the Issuer
- Within the Time-to-Live (TTL) of the Virtual NIN, carry out the verification
As a part of VNIN Validation (as opposed to VNIN Verification, which takes place at the NIMC backend), once the VNIN has been handed over by the Issuer to the Relying Party, the latter, during entry into their own CRM interface, may wish to validate that the token was correctly entered.
This can be accomplished by using a library that validates the ISO/IEC 7064,MOD 1271_36 specification. It’s a simple process, (not mod661_26 as previously listed), similar to when one enters a Credit card PAN number into a portal and computes the LUHN Digit, or with a Passport or ID Card and the ICAO checksum is computed… Before the number is sent to a backend for VERIFICATION, its composition can first be VALIDATED offline.
¶ Format of the QR Code
To simplify the Virtual NIN Process, the NIMC utilises ISO/IEC 18004:2015 Symbology, commonly known as Quick Response (or QR Code) for the presentation of the Enterprise ID to a Virtual NIN Issuer.
The Issuer may only use the NIMC MobileID application for the exercise listed above. Your average QR Code reader will only display the content of the Barcode - nothing else!
The QR Code contains a very simple payload as shown below:
{h:'value of enterprise long ID'}
Where ‘value of enterprise long ID’ is the LongID number issued to your Enterprise as a part of the Production Credentials by the NIMC.
An example is shown below
{h:'s.jEumt27otkr3QEp7r6qHaQyK'}
Where s.jEumt27otkr3QEp7r6qHaQyK is your Enterprise Long ID (not the 6-digit short code which comes in the format 123456).
¶ Support Services for Feature Phones & Smartphones with unsupported Operating Systems
In order to provide Support Services to those who have Feature Phones (or Smartphones with unsupported Operating Systems) rather than Smartphones that meet the MobileID requirements, the following options will become available shortly:
¶ USSD Services
- Virtual NIN Issuance
- UserID Retrieval
- UserID/OTP combination retrieval
- Others
¶ Two-way SMS Services
- Virtual NIN Issuance
- UserID Retrieval
- UserID/OTP combination retrieval
Please note that these services are only available to those with Active NINs. In other words, the person at some point in time or another, has visited a NIMC-approved Biometric centre to update their record.
NINs that were issued as a part of BVN harmonisation processes WILL NOT be available as their Digital Profiles will not be built unless and until the individual complies with the Government regulations as described above.
¶ Virtual NIN Verification
¶ Introduction
Nigeria’s National Identity Management System (NIMS) plays a transformational role across many sectors yet, as with any system that collects, uses, and stores personal data, it also creates challenges of privacy and data protection. Protecting personal data in the NIMS requires not only a comprehensive legal framework, but also a “Privacy and Security Design” (PbD) approach that accentuates Data Privacy and Protection the default setting and embeds security and encryption into the technical design from the get gp rather than retrofitting it. Whilst we may not achieve PbS from the get go, that is the objective, and subsequent updates edge closer to full compliance.
The biggest threat to Persona Information arises when a third party is granted access to a NIN-holder’s personal data during a verification exercise.
To ensure Data Privacy, transparency and security in the NIMS, the National Identity Management Commission (NIMC) has implemented Tokenization of the National Identification Number (NIN). Tokenization in Data Security is the process of substituting a sensitive data element with a non-sensitive equivalent, referred to as a token, that has no extrinsic or exploitable meaning or value. In the context of the NIN, it is the swapping of the NIN which is the sensitive data element with a token referred to as the virtual NIN, to be used in place of the actual NIN for verification purposes.
The virtual NIN is a unique 16-character alphanumeric token comprising of 12 digits, sandwiched between 4 alphabets (and possibly numbers for the 2 characters, being the checksum) - 2 on each end with no correlation to the issuer’s NIN. An example of a Virtual NIN is: AB-0123-4567-8910-YZ
(The hyphens are not part of the virtual NIN and should not be passed when making an API call.
They are only used for easier readability and presentation).
The virtual NIN is Enterprise-specific i.e. it cannot be verified by another Enterprise regardless of its validity. It is also time-bound with an expiry period of 72 hours (by default) after issuance and may only be verified once. The virtual NIN is all about Self-Sovereign Identity - Power shift to the ID Holder.
This documentation serves as guide to aid Enterprises to integrate the secure virtual NIN verification API within their existing systems.
The data returned from the NIMC MWS Virtual NIN Verification endpoints are encrypted. Below is a test Private Key to decrypt your data in the test Environment.
¶ IMPORTANT
The Federal Government of Nigeria will make it illegal and unlawful to store or attempt to verify a RAW 11-digit NIN after the cutoff date.
Any sensitive data (including but not limited to the National Identification Number NIN), stored in any database without the prior written consent of the NIMC, and then, only after a thorough forensic audit, will be deemed illegal.
The NIMC as Custodian of Personal Identity in the country, will disable all access to any resource that requests the raw NIN. Where it is found that an Enterprise or entity is offering services that processes or provides personal information FROM ANY DATABASE using the raw NIN, the Federal Government of Nigeria at its discretion, may pursue and prosecute any and all defaulters to the full extent of the law.
Please be advised.
The effective cutoff date is set for the 31st December 2021.
¶ The Steps
¶ Test Private Key
¶ Preamble
-
A PRIVATE Key is used to decrypt data that was either previously encrypted with the same key (but used by the owner of the private key), or using the Public Key, which itself is derived from that same Private Key.
-
Whilst a PUBLIC key may be shared with 3rd parties, your PRIVATE KEY must NEVER be shared with any other party - even if you are sitting behind the API of another party instead of directly to the NIMC. Therefore, sharing production PRIVATE KEYS is NOT ALLOWED UNDER ANY CIRCUMSTANCES.
-
The test keys provided here are simply for that - testing.
-
In production, the Virtual NIN is issued by the ID Holder, not by the NIMC and not the verifier (or Relying Party). The ability to generate Virtual NINs in the test environment is simply designed to introduce the Developer to the concepts, and to integrate the RESTful APIs in your systems.
-
The Private Key uses PKCS1_OAEP Padding - important for those wishing to use other tools to test the payload decryption.
-
The payload is encoded using base64 (as it would be difficult to include binary data in a JSON object).
¶ Example decryption using OpenSSL
To use the example below, you will need to:
- install Linux (or Windows) with base64 and openssl installed
- have generated a request to verify a Virtual NIN and received back a JSON object
- extract the value in the “data” element of that JSON object and save to a file named testpayload.b64, as it is a base64-encoded value
- save the Private Key below as testkey.key
¶ The example using OpenSSL
base64 -d testpayload.b64 |openssl rsautl -decrypt -oaep -inkey testkey.key
Where testpayload.b64 is the actual data contained in the “data” element of the returned payload and testkey.key is the Private Key shown below, stored in a text file. Please also note the -oaep switch, which is the PKCS1_OAEP padding.
¶ The Test Private Key
-----BEGIN RSA PRIVATE KEY-----
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
-----END RSA PRIVATE KEY-----
¶ Retrieving your API Keys
This document describes how to authorize API calls. Your Production API keys will be made available when all onboarding and Due Diligence processes at the NIMC have been completed.
¶ Authorization Sample
x-api-key: nudjthujPIIi0FnmnYGKaXj1mDWfjhgvjhgj
¶ Test Endpoints
The Test endpoints are divided into three four categories:
¶ 1. Token Generation
https://testtk.nimc.gov.ng/api/v1/tokenization/vNIN
¶ 2. Direct Virtual NIN Verification
https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/direct/vNIN
¶ 3. Indirect Virtual NIN Verification
https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/indirect/vNIN
¶ 4. QR Code Verification
URL: https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/qrCodeVerification/direct
URL: https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/qrCodeVerification/direct
RPShortCode: 123456
agentID: ABCDEF-8910
level: b || f || n || t
hash: 9be9010b337d6c54a289190d677258aa6dd0e2d6 || fc732136f5542705b01f12d676b4ed42bc65d938 || 1f5aca444552ed0f5b1a0e3bbaa2563f94bb7ab5 || SU572739355475XP
User(UVWXYZ-0000)
URL: https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/qrCodeVerification/direct
RPShortCode: 123456
agentID: ABCDEF-8910
level: b || f || n || t
hash: 8af882502e3cd6500b074fe3bf283388ca4526cb || 3828cd1afd34dbba0945bc1a2a85547cb2d86267 || ee8da029fb8f72b46fe7363e1f60c374381f2834 || NT649834954852WX
¶ The DeviceID Specification
Due to the possible high demands for API calls and low latency responses, it has become apparent that some (if not all) operators, have implemented automated systems for these API calls using the IDs of Agents.
The Federal Government, in the implementation of the Tokenization process, makes a very clear distinction between Agent Management and Device Management.
From the September 25th 2022, the Tokenization platform will implement rate capping on UserIDs (agent IDs). Where it is found that a UserID makes several calls that are not humanly possible, the agentID will be blocked and the UserID suspended.
Each Operator (and any other organization requiring the use of automated calls for middleware implementations), is required to make a request to the National Identity Management Commission (NIMC), for a deviceID, which will be used for specific calls.
This however, DOES NOT negate the requirement to include the ID of the Agent making the request, as every request still has a natural person behind it. The NIMC needs to know who is doing what and from where.
The distinction is that 100 requests in 60 seconds might have 47 different AgentIDs, but the same deviceID.
The DeviceID takes the format of a 128-bit label, following the specifications of RFC4122.
¶ Test Environment
¶ Token Generation With DeviceID (Digital channels Only, service-service communication)
Response Object
{
"success": true,
"data":
"EUnmRG10BE45G2OBLEADclfQS9FnXyzvBMCkIdxe+CuwtgdZ//8NO+qh+a5d1rj+KMMbOd1hz77i/R4K3kegYhUd5
nnX4exIgeFBTLisoL5oAGHYhvzY+CaVNpCdguNu5XTBWK8A6x3RktiSUIMGaSBZB8rRVWRmcieVq9IK+4sbGlY6b
VS4oaQ6aK7k3m5J+rqj7QNXQwRSAl/OJD+Rt4EFvJ+ivrSQdAzNVe1KVCuvIqSwkqTZwKQ8LgWphT0QUKt0UZDA
QNddnlysXzd7B375iQIcXie7EcilD7oL8LGPAIIJAYGdWqh/Je3OlHxwfvaBmTq4x4t5uUe+2O5PLu6mViGopNNMdTrcq
egYNMTN0G/3bV4jIqwWMxCZnNR5bVFEIfdevYA/GjtQyemPkzjF4UXderVUmb89u9PP0X80mLHrzQeOS0ajAsPktW
Trp9Oe5z90nxSbD3Mxl15CjJyqENgdDsCSfkPABpm0ndS9m19ptPMHx/BuqQsf4RTx"
}
Request Object
-URL: https://testtk.nimc.gov.ng/api/v1/tokenization/device/vNIN
-RPShortCode: 000000
-uin: 00000000000
-deviceid: 06e2d108-2dd9-11ed-b14d-265bfdfa7a52
¶ Direct Virtual NIN Verification with DeviceID
Response Object
{
"success": true,
"data":
"OzHaxle6UREooR0rbP1D5yIsNv8zN6CH7767bouGUxdsI8MUhHSZVT2Mdo2mv/ZeR4F9okXrrTk3yOtbp9pbB6S6Z
HX/G34aiffBF76Yn4PHEr6an0b4dkbXvw7xMSbb/t+iPG7pP/VCmd4MYG8gj/BAyIzuaWvz/j27wreplFz8VdvaK7cdKQ
Q57cLVizdJGpfYfLVqvtgRXP/EKrO9gz9qO91qu/j4xqK9pq0SxhH2HzD++4ZI7ZZtXx5DvZMXPJ/qmMbNsb+2nyV2Zc
WK+qzI15/xpBGxZBC2UQLg7WvlFVNg/n6RND05tZtH84QeCrX8wXF+XhC9RNJoFUjW5+D6ZBNaPnazlOFhI31nIC
hye9r+tkgAPkihJeywTkv++/zFft8N4JdZwohJ9wvu4FILveQ5r3y2XqeMzRdnd6Q+Ec0EAV7NtiETT/0wJ/Yv5nRUQVPn
kmMazW3m2DzMuLjUbpr1CtCHaFABPz/fOwzI2+JL7m+9ZvRuQ4pj8edK",
"photograph": "/9j/4AAQSkZJRgABAgAAAQABAAD/”
}
Request Object
-URL: https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/direct/device/vNIN
Headers
x-api-key: RPShortCode's apikey
Request Body
-RPShortCode: 000000
-vNIN: MX123456789104PQ
-deviceid: 06e2d108-2dd9-11ed-b14d-265bfdfa7a52
¶ Indirect Virtual NIN Verification with DeviceID
Request Object
{
"success": true,
"data":
"OzHaxle6UREooR0rbP1D5yIsNv8zN6CH7767bouGUxdsI8MUhHSZVT2Mdo2mv/ZeR4F9okXrrTk3yOtbp9pbB6S6Z
HX/G34aiffBF76Yn4PHEr6an0b4dkbXvw7xMSbb/t+iPG7pP/VCmd4MYG8gj/BAyIzuaWvz/j27wreplFz8VdvaK7cdKQ
Q57cLVizdJGpfYfLVqvtgRXP/EKrO9gz9qO91qu/j4xqK9pq0SxhH2HzD++4ZI7ZZtXx5DvZMXPJ/qmMbNsb+2nyV2Zc
WK+qzI15/xpBGxZBC2UQLg7WvlFVNg/n6RND05tZtH84QeCrX8wXF+XhC9RNJoFUjW5+D6ZBNaPnazlOFhI31nIC
hye9r+tkgAPkihJeywTkv++/zFft8N4JdZwohJ9wvu4FILveQ5r3y2XqeMzRdnd6Q+Ec0EAV7NtiETT/0wJ/Yv5nRUQVPn
kmMazW3m2DzMuLjUbpr1CtCHaFABPz/fOwzI2+JL7m+9ZvRuQ4pj8edK",
"photograph": "/9j/4AAQSkZJRgABAgAAAQABAAD/”
}
Request Object
-URL: https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/indirect/device/vNIN
Headers
x-api-key: RPShortCode's apikey
Request Body
-integratorShortCode: 123456
-RPShortCode: 000000
-vNIN: MX123456789104PQ
-deviceid: 06e2d108-2dd9-11ed-b14d-265bfdfa7a52
¶ QR Code Verification with DeviceID
Response Object
{
"success": true,
"data":
"OzHaxle6UREooR0rbP1D5yIsNv8zN6CH7767bouGUxdsI8MUhHSZVT2Mdo2mv/ZeR4F9okXrrTk3yOtbp9pbB6S6Z
HX/G34aiffBF76Yn4PHEr6an0b4dkbXvw7xMSbb/t+iPG7pP/VCmd4MYG8gj/BAyIzuaWvz/j27wreplFz8VdvaK7cdKQ
Q57cLVizdJGpfYfLVqvtgRXP/EKrO9gz9qO91qu/j4xqK9pq0SxhH2HzD++4ZI7ZZtXx5DvZMXPJ/qmMbNsb+2nyV2Zc
WK+qzI15/xpBGxZBC2UQLg7WvlFVNg/n6RND05tZtH84QeCrX8wXF+XhC9RNJoFUjW5+D6ZBNaPnazlOFhI31nIC
hye9r+tkgAPkihJeywTkv++/zFft8N4JdZwohJ9wvu4FILveQ5r3y2XqeMzRdnd6Q+Ec0EAV7NtiETT/0wJ/Yv5nRUQVPn
kmMazW3m2DzMuLjUbpr1CtCHaFABPz/fOwzI2+JL7m+9ZvRuQ4pj8edK",
"photograph": "/9j/4AAQSkZJRgABAgAAAQABAAD/”
}
Request Object
-URL: https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/qrCodeVerification/device/direct
-RPShortCode: 000000
-hash: 9be9010b337d6c54a289190d677258aa6dd0e2d6 ||
fc732136f5542705b01f12d676b4ed42bc65d938 ||
1f5aca444552ed0f5b1a0e3bbaa2563f94bb7ab5 || SU572739355475XP
-level: b || f || n || t
-deviceid: 06e2d108-2dd9-11ed-b14d-265bfdfa7a52
¶ Production Environment
¶ Token Generation With DeviceID (Telcos Only)
Request Object
-URL: https://tk.nimc.gov.ng/api/v1/tokenization/device/vNIN
-RPShortCode: 000000
-uin: 00000000000
-deviceid: 06e2d108-2dd9-11ed-b14d-265bfdfa7a52
¶ Direct Virtual NIN Verification with DeviceID
Request Object
-URL: https://tk.nimc.gov.ng/api/v1/apiVerification/enterprise/direct/device/vNIN
Headers
x-api-key: RPShortCode's apiKey
Request Body
-RPShortCode: 000000
-vNIN: MX123456789104PQ
-deviceid: 06e2d108-2dd9-11ed-b14d-265bfdfa7a52
¶ Indirect Virtual NIN Verification with DeviceID
Request Object
-URL: https://tk.nimc.gov.ng/api/v1/apiVerification/enterprise/indirect/device/vNIN
Headers
x-api-key: RPShortCode's apiKey
Request Body
-integratorShortCode: 123456
-RPShortCode: 000000
-vNIN: MX123456789104PQ
-deviceid: 06e2d108-2dd9-11ed-b14d-265bfdfa7a52● QR Code Verification with DeviceID
Request Object
-URL: https://auth.nimc.gov.ng/api/v1/qrCodeVerification/device/direct
-RPShortCode: 000000
-hash: 9be9010b337d6c54a289190d677258aa6dd0e2d6 ||
fc732136f5542705b01f12d676b4ed42bc65d938 ||
1f5aca444552ed0f5b1a0e3bbaa2563f94bb7ab5 || SU572739355475XP
-level: b || f || n || t
-deviceid: 06e2d108-2dd9-11ed-b14d-265bfdfa7a52
¶ QR Code Verification with DeviceID
Request Object
-URL: https://auth.nimc.gov.ng/api/v1/qrCodeVerification/device/direct
-RPShortCode: 000000
-hash: 9be9010b337d6c54a289190d677258aa6dd0e2d6 ||
fc732136f5542705b01f12d676b4ed42bc65d938 ||
1f5aca444552ed0f5b1a0e3bbaa2563f94bb7ab5 || SU572739355475XP
-level: b || f || n || t
-deviceid: 06e2d108-2dd9-11ed-b14d-265bfdfa7a52
# Production Endpoints
**Three** Production endpoints are available:
## 1. Direct Virtual NIN Verification
https://tk.nimc.gov.ng/api/v1/apiVerification/enterprise/direct/vNIN
## 2. Indirect Virtual NIN Verification
https://tk.nimc.gov.ng/api/v1/apiVerification/enterprise/indirect/vNIN
> For more information on the differences between direct and indirect virtual NIN verification, please [click here](/en/privacy/data-protection/tokenization)
## 3. QR Code Verifications
https://auth.nimc.gov.ng/api/v1/qrCodeVerification/direct
# Breakdown
# Breakdown {.tabset}
## Generate Virtual NIN (only for test)
`URL: https://testtk.nimc.gov.ng/api/v1/tokenization/vNIN`
### METHOD: POST
### HEADERS
**x-api-key**: Test API key issued to a Relying Party
### Body: `urlencoded`
| Component | Value | Comment |
|------|------------------|-------------------------------------------|
| userID | ABCDEF-8910 | UserID of the NIN Holder, issued to a Relying Party. |
| shortCode | 123456 | Shortcode of the Relying Party (RP). |
### Example Request
```javascript
curl --location --request POST 'https://testtk.nimc.gov.ng/api/v1/tokenization/vNIN' \
--header 'x-api-key: nudjthujPIIi0FnmnYGKaXj1mDWfjhgvjhgj' \
--data-urlencode 'userID=ABCDEF-8910' \
--data-urlencode 'shortCode=123456'
¶ Example Response 201 Created
¶ Body: Header(20)
{
"success": true,
"data": "SZ33888522336766"
}
¶ Direct Enterprise Virtual NIN Verification
URL: https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/direct/vNIN
¶ METHOD: POST
¶ HEADERS
x-api-key: nudjthujPIIi0FnmnYGKaXj1mDWfjhgvjhgj
¶ Body: urlencoded
| Component | Value | Comment |
|---|---|---|
| agentID | ABCDEF-8910 | UserID of the Agent representing the Relying Party. |
| vNIN | CC365662783459TT | Virtual NIN issued to the Relying Party (RP). |
| RPShortCode | 123456 | ShortCode of the Relying Party. |
¶ Example Request
curl --location --request POST 'https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/direct/vNIN' \
--header 'x-api-key: nudjthujPIIi0FnmnYGKaXj1mDWfjhgvjhgj' \
--data-urlencode 'agentID=ABCDEF-8910' \
--data-urlencode 'vNIN=XY4866768954688I' \
--data-urlencode 'RPShortCode=123456'
¶ Example Response 200 OK
¶ Body: Header(21)
{
"success": true,
"data": "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
¶ Indirect Enterprise Virtual NIN Verification
URL: https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/indirect/vNIN
¶ METHOD: POST
¶ HEADERS
x-api-key: nudjthujPIIi0FnmnYGKaXj1mDWfjhgvjhgj
¶ Body: urlencoded
| Component | Value | Comment |
|---|---|---|
| agentID | ABCDEF-8910 | UserID of the Agent representing the Relying Party. |
| vNIN | MB283676965743PW | Virtual NIN issued to the Relying Party (RP). |
| integratorShortCode | 123456 | ShortCode of the Integrator (not RP). |
| RPShortCode | 123456 | RP (entity that the Agent works for, not Integrator). For brevity, the code is the same for test. In production, these codes may not be the same UNLESS the RP is also the Integrator |
¶ Example Request
curl --location --request POST 'https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/indirect/vNIN' \
--header 'x-api-key: nudjthujPIIi0FnmnYGKaXj1mDWfjhgvjhgj' \
--data-urlencode 'agentID=ABCDEF-8910' \
--data-urlencode 'vNIN=MB283676965743PW' \
--data-urlencode 'integratorShortCode=123456' \
--data-urlencode 'RPShortCode=123456'
¶ Example Response 200 OK
¶ Body: Header(21)
{
"success": true,
"data": "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
¶ Error Handling Status Codes
¶ 422: ‘RPShortCode’ || ‘vNIN’ || ‘agentID’ || ‘x-api-key’ field is missing | empty | invalid
This occurs if one or more params is missing
Message: {success: false, message: "Please complete the required fields"} || {success: false, message: "No apiKey provided."}
¶ 403: ‘x-api-key’ is wrong
This occurs if the api-key provided is faulty
Message: {success: false,message:"Invalid request"}
¶ 200: Agent has an inactive account
This occurs if an agent has been deactivated by the Relying Party
Message: {success: false,message: "You do not have an active account for this enterprise"}
¶ 200: Agent does not belong to the Relying Party
To be able to verify on behalf of a relying party, the Agent must have Role Based Access Credentials assigned by the RP's designated administrator
Message: {success: false,message: `Agent does not belong to this enterprise.`}
¶ 200: Agent with insufficient credit
This occurs if the Relying Party has insufficent credits in their account
Message: {success: false,message: "You do not have credit to perform this verification"}
¶ 200: Encryption Error
One of a variety of encryption mistakes
Message: {success: false, message: 'Error while trying to encrypt data'}
¶ 200: Invalid Virtual NIN (ISO Specification)
The Checksum of the Viirtual NIN is based on an ISO specification. If it does not match, an error is thrown. It is expected that the developer would test for valid Virtual NINS prior to sending to the backend.
Message: {success: false, message: 'Invalid Virtual NIN.'}
¶ 200: Wrong Virtual NIN
This occurs if a Virtual NIN is either not assigned to this Relying Party... or it is simply made up!
Message: {success: false, message: "Virtual NIN does not exist."}
¶ 200: Virtual NIN already verified
This occurs if a Virtual NIN has been already verified
Message: {success: false, message: "This vNIN has been verified by an organization with short code 123456 on 2000-01-15T11:40:41.000Z"}
¶ Payload Definitions
camelCasing is used in the elements
¶ Constants
Value lengths are fixed unless stated to the contrary
| Element | Description | Example | Length |
|---|---|---|---|
| vNIN | Virtual NIN | s.yR3rRsjdTa15EkDfkXqnfVWL | 40 CHARS |
| userid | UserID of the Issuer of the vNIN | ABCDEF-1234 | 11 CHARS |
| msisdn | Mobile Number associated with the Person | 2348001234567 | 14 CHARS |
| txid | TransactionID of the verification | 299a5dd6-ec34-431d-b9a7-5e27a4b46107 | 40 CHARS |
| ts | TimeStamp (is based on NTP Specs) | 2021-09-02 13:17:50 | 19 CHARS |
| firstName | First Name of VNIN Issuer | NGOZI | 40 CHARS (max) |
| middleName | Optional Middle Name of VNIN Issuer | BLESSING | 40 CHARS (max) |
| surname | surname of VNIN Issuer | IBUKUN | 40 CHARS (max) |
¶ Optional
| Element | Description | Example | Access Levels |
|---|---|---|---|
| gender | Male or Female | M | 3-4 |
| dateOfBirth | Birth Date of Issuer in ICAO Format | 01 JAN 2001 | 3-4 |
| photograph | Facial Portrait of VNIN Issuer | Base64 | 2-4 |
| trustedNumber | MSISDN of VNIN Issuer as registered at NIMC | 2348001234567 | 4 |
¶ Credit Consumption
To participate in the new pricing structure, the NIMC will henceforth not be charging verificatiions in units of Naira. You purchase verification Credits as shown in the tables above, but for each verification, you are charged based on the Access Level approved by the NIMC.
The baseline rate for Access Level 1 is 1 Credit.
Please study the table below for details of how Access Level verifications are charged.
| Access Level | Credit(s) |
|---|---|
| AL 1 | 1 |
| AL 2 | 2 |
| AL 3 | 3 |
| AL 4 | 5 |
¶ Fetching Images
In order to reduce the payload for any access level requiring images, a URL is provided to fetch the image from a high-performance, dedicated image server, capable of low latency responses.
¶ POST Get Image By UserID
¶ Service https://sftp1.nimc.gov.ng:7081/api/v1/enterprise/imageService/
The Image Fetch API takes the userID and returns the image of the user. To get an image, make a POST request to the /enterprise/imageService/ endpoint:
It also accepts api-key as headers. api-key is the key available on your enterprise platform.
¶ HEADERS
¶ Example Response 200 OK
¶ API-Key: iMK90h$lUTwaNw#gHJJKOtKJ7u2LUalcqzI05uq9C9wTLyr8R
¶ Request Body
¶ userID: ABCDEF-8910
¶ RPShortCode: 123456
¶ Example Request
curl --location --request POST 'https://sftp1.nimc.gov.ng:7081/api/v1/enterprise/imageService/' \
--header 'api-key: iMK90h$lUTwaNw#gHJJKOtKJ7u2LUalcqzI05uq9C9wTLyr8R' \
--data-urlencode 'userID=ABCDEF-8910'
--data-urlencode 'RPShortCode=123456'
¶ Checking your Tokenization Credit Status
¶ Preamble
In order to ensure that your enhanced verification workflow is uninterrupted, it is necessary to have available credit at all times.
Given the potential delays in procurement of replenishement credit, the following APIs are now available:
¶ Test Environment
- Request Object
HTTP Method: GET
URL: https://testtk.nimc.gov.ng/api/v1/apiVerification/enterprise/creditInfo?RPShortCode=123456
Headers:
x-api-key:
Query Param: RPShortCode
- Response Object
{
"success": true,
"data": "yMdK68DePUitoVLiTnyYJf+pGVXGqRBLJRjbrpssmAFTSN5FtatSV17yjgJljBj5PhjwJt5oO3buOZDjVG0I/m1yM0eXH3DhyCnL/OQHZ5wXxtx18IomID/oj4Rbokc4S9eFE1uaFpME7qcb64LqNVp6X4dBoQ3JXH6q5c7MMfR7p6k920+jupNVhBSJ25yTDyvN0DKF63Kz8IMPRmbANXroj7j51AaZqI5RD8muLvd7wPdjhIKL++3HyJeNIlTTmr68AwCvXTOP6QiacvqSip4cNDJGA/mWVu7CQGNBoeL+0Ii+PzFIxJs574ANfov1sqDN+brNaX+ezTZ+Swq0WnP9C3kVVJ8A6+Qu162PWRdW0W9QCmwaSaZkrmy2KdTCFz5iPB4n9h7n9GBNeYGT50aTAwkU5025UBGBn2nXKDFNcWxzbrpUo5K/D+p2AZSM1YoqDQOM8FB6rdHM4eBGSlBbp5//v3PsYn1C5KWaT5nvIpcok3i4EudouXIl9gkW"
}
¶ Production Environment
- Request Object
HTTP Method: GET
URL: https://tk.nimc.gov.ng/api/v1/apiVerification/enterprise/creditInfo?RPShortCode=123456
Headers:
x-api-key:
Query Param: RPShortCode
- Response Object
{
"success": true,
"data": "yMdK68DePUitoVLiTnyYJf+pGVXGqRBLJRjbrpssmAFTSN5FtatSV17yjgJljBj5PhjwJt5oO3buOZDjVG0I/m1yM0eXH3DhyCnL/OQHZ5wXxtx18IomID/oj4Rbokc4S9eFE1uaFpME7qcb64LqNVp6X4dBoQ3JXH6q5c7MMfR7p6k920+jupNVhBSJ25yTDyvN0DKF63Kz8IMPRmbANXroj7j51AaZqI5RD8muLvd7wPdjhIKL++3HyJeNIlTTmr68AwCvXTOP6QiacvqSip4cNDJGA/mWVu7CQGNBoeL+0Ii+PzFIxJs574ANfov1sqDN+brNaX+ezTZ+Swq0WnP9C3kVVJ8A6+Qu162PWRdW0W9QCmwaSaZkrmy2KdTCFz5iPB4n9h7n9GBNeYGT50aTAwkU5025UBGBn2nXKDFNcWxzbrpUo5K/D+p2AZSM1YoqDQOM8FB6rdHM4eBGSlBbp5//v3PsYn1C5KWaT5nvIpcok3i4EudouXIl9gkW"
}
¶ Checking your Partners Verification Usage
¶ Production Environment
- Request Object (Query Params)
Query Param -
RPShortCode: 1234567 (Partner's shortCode) must be 7 digits
integratorShortCode: 000000 (Licensed verification agent) must be 6 digits
deviceid: 0321ef469-2ee9-11ed-b14d-453af18a7a31
duration: today
from: 2024-01-01 (Start date)
to: 2024-01-12 (End date)
todayTime: false (Always equal to false)
HTTP Method: GET
URL: https://tk.nimc.gov.ng/api/v1/apiVerification/enterprise/statisticsForPartners/device?RPShortCode=1234567&integratorShortCode=000000&deviceid=0321ef469-2ee9-11ed-b14d-453af18a7a31&duration=today&from=2024-01-01&to=2024-03-21&todayTime=false
Headers:
x-api-key: dMlUTwaNw#gHtKJ7u2LUalcqzI05uq9C9wTLyr8R
¶ Payload Formats
There are various data sets depending on the access levels approved by the NIMC.
All data will be transmitted according to industry best practices for Transparent Data Encryption.
That is to say in transit, at rest and in process, the data will be secured as best possible.
All Verification Entities (Relying Parties or RP) will henceforth be required to adhere strictly to these steps, including for the minimal dataset that the Relying Party will be permitted to persist. - ALL PERMITTED PII MUST BE ENCRYPTED AT REST in your databases.
¶ PKI Cryptography
Key Format: RSA
Modulus Length: 3,072b
Padding: PKCS1_OAEP
This is the basic access level as defined by the NIMC.
¶ Payload
const al1 = {
vNIN,
userid,
txid,
ts,
firstName,
middleName,
surname
};
This is the next higher access level as defined by the NIMC.
¶ Payload
const al2 = {
vNIN,
userid,
txid,
ts,
firstName,
middleName,
surname,
photograph
};
This is the advanced access level as defined by the NIMC.
¶ Payload
const al3 = {
vNIN,
userid,
txid,
ts,
firstName,
middleName,
surname,
photograph,
dateOfBirth
};
This is the highest access level as defined by the NIMC.
¶ Payload
const al4 = {
vNIN,
userid,
txid,
ts,
firstName,
middleName,
surname,
photograph,
gender,
nationality,
dateOfBirth,
msisdn
};
¶ Telco-specific API Calls
For more information regarding APIs for the Telecoms Industry, please click here.
¶ Further Reading
- MWS Enterprise User Guide
- ISO/IEC 7064:2003 Security techniques
- NodeJS Support for Check Digit Validation
- Array of Validators