Version History:
Version | Description | Author | Date (dd/mm/yyyy) |
1.0.0 | DRAP eKYC Journey [EFR] Document | Ajai Antony | 07/06/2024 |
|
|
|
|
CLASSIFICATION: PUBLIC
These APIs are used to onboard a customer via e-KYC by authorized entities associated with Lulu.
EFR as the provider has multiple options to complete an EKYC.
Web HTML Model
Web SDK Model
Mobile SDK Model
Web HTML model
The API provides encrypted HTML page content with a unique e-KYC request Id as a response. The sequence diagram below provides further insight into the rich customer onboarding experience.
EFR WEB SDK and EFR WEB SDK integration sample project:
https://drive.google.com/file/d/14vquYOenwLFjcSJ2-XmVqPxgZ3QUSTea/view?usp=sharing
Web SDK Model
With this model, Partner will send an EKYC request to CDP and the partner initiate the EFR SDKs. EFR SDK will take care of OCR and Face liveness.
Mobile SDK Model
With this model, Partner will send an EKYC request to CDP and the partner initiate the EFR SDKs. EFR SDK will take care of OCR and Face liveness.
EFR Development Kit - Android & IOS:
https://drive.google.com/file/d/11XvjE-sFBBlFVjuwZUIMLdBKyjJhW0em/view?usp=drive_link
APIs
Access token API (API 1)
An access token is the key to the gateway to access any other API. The API will return the access token if the user is successfully authenticated and has authorization to access these services. Every access token is tagged with validity, and the expiry duration is echoed in the response for the calling application to manage the state accordingly. A token that is used after its validity period will restrict access to any services, and a new token will be generated in this case.
API | https://{{baseUrl}}/auth/realms/cdp/protocol/openid-connect/token |
Method | POST |
Headers | Content-Type : application/x-www-form-urlencoded |
Access Token Payload | --data-urlencode 'grant_type=password' \ --data-urlencode 'scope=api://3a3f52a1-1b64-4c27-81f0-50a6ca01324d/customer' \ --data-urlencode 'client_id=<<client_id>>' \ --data-urlencode 'client_secret=<<secret>>' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'username=<<username>>' \ --data-urlencode 'password=<<password>>' |
Refresh Token Payload | --data-urlencode 'grant_type=password' \ --data-urlencode 'client_id=<<client_id>>' \ --data-urlencode 'client_secret=<<secret>>' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'refresh_token=<<refreshToken>>' \ |
Response | {
"token_type": "bearer",
"access_token": "<<access_token_value>>",
"expires_in": 7199,
"refresh_expires_in": 7199,
"refresh_token": "<<refresh_token_value>>",
"scope": "----",
"not-before-policy": 0,
"session_state": "<<session_state>>"
}
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | MANDATORY | Content type |
Payload
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
grant_type | String | 10 | MANDATORY | Grant type. Will up provided |
scope | String | 60 | CONDITIONAL | Scope name. Will be provided |
client_id | String | 60 | MANDATORY | Client Id. Will be provided |
client_secret | String | 60 | MANDATORY | Client secret. Will be provided |
username | String | 60 | MANDATORY | Admin user name |
password | String | 60 | MANDATORY | Admin password |
Response
Name | Data Type | Max Length | Description |
|---|---|---|---|
token_type | String | - | Token type |
scope | String | - | Scope details |
access_token | String | 600 | Access token to access the APIs |
refresh_token | String | 600 | refresh token to refresh the Token. |
expires_in | Integer | - | Token expiry time in seconds |
refresh_expires_in | Integer | - | Refresh Token expiry time in seconds |
Request e-KYC ( API 2)
This API is used to create an e-KYC request in order to use the e-KYC, and it will check whether the requester has the authorization to use the provided e-KYC solution.
The Request e-KYC API will provide a success result with a unique e-KYC Request Id and encrypted HTML page content or SDK configuration data based on the e-KYC provider and e-KYC model.
API | |
Authorization | Bearer Token |
Method | POST |
Headers | Content-Type:application/json |
Payload | {
"channel": "WEB",
"ekyc_provider": "EFR",
"ekyc_model": "WEB",
"ecrn": "<<ecrn>>",
"primary_mobile_number": "<<customer_mobile>>",
"email_id": "<<customer_email_id>>"
}
|
Success Response for WEB model Http status Code :200 | {
"status": "success",
"statusCode": 200,
"data": {
"ekyc_request_id": "4e41d40a-6f16-4874-977b-017798d1e583",
"ekyc_request_data": {
"ekyc_portal_html": "<<encrypted_base_64_ekyc_portal_html_if_any>>"
}
}
}
|
Success Response for SDK model Http status Code :200 | {
"status": "success",
"statusCode": 200,
"data": {
"ekyc_request_id": "ab7562a0-e4c8-4873-8160-ae701b10eb3c",
"ekyc_request_data": {
"ekyc_sdk_configuration": "<<ekyc sdk configuration>>",
"ekyc_sdk_secretKey": {
"code": 281419905,
"value": "bkZjS4KYaHWoFdMKOB73enCsU1HiiRlwM1y1nnN6WHQRY5g3g3J17rJKAWUnGNOGh+LGDUU3dXN0KILvkN1c/w==",
"expiry": "2023-03-08 14:00:00"
}
}
}
}
|
Bad Request Http status Code:200 | {
"status": "failure",
"statusCode": 400,
"errorCode": 400,
"message": "Invalid primaryMobileNumber,ekycProvider is mandatory,channel is mandatory"
}
|
Failure Response e-KYC not Configured Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 46001,
"message": "eKYC not Configured for the Agent!"
}
|
Failure Response Invalid e-KYC Provider Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 46002,
"message": "Invalid eKYC Provider"
}
|
Failure Response Invalid e-KYC Model for e-KYC Provide Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 46003,
"message": "Invalid eKYC Model for eKYC Provider!"
}
|
Authentication Failure Http status Code :401 | {
"timestamp": "2022-12-05T13:44:31.557+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/api/v1/request"
}
|
Partner (e-KYC Provider)Service Failure Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 47001,
"message": "EFR eKYC Service is Down!"
}
{
"status": "failure",
"statusCode": 500,
"errorCode": 47002,
"message": "EFR Web Portal is Down!"
}
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | MANDATORY | Content type |
Authorization | String | MANDATORY | Authorization Token |
Payload
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
channel | String | 20 | MANDATORY | Channel |
ekyc_provider / ekycProvider | String | 30 | MANDATORY | EKYC Provider |
ekyc_model / ekycModel | String | 30 | MANDATORY | EKYC Model: WEB / FACE_WEB / SDK |
ecrn | String | 255 | CONDITIONAL | CDP customer unique identification Number, provide only for existing CDP customer. |
primary_mobile_number PrimaryMobileNumber | String | 20 | CONDITIONAL | Primary Mobile Number |
email_id / emailId | String | 120 | CONDITIONAL | Email ID |
Response
Name | Data Type | Max Length | Description |
|---|---|---|---|
status | String | 255 | status description |
status_code | Int | - | Status code |
message | String | 255 | Message |
data | Object | - | Data object |
ekyc_request_id | String | 50 | e-KYC Request unique identification number |
ekyc_request_data | Object | - | Data object |
ekyc_portal_html | String | 4000 | Base64 encrypted e-KYC Portal HTML content only for the WEB e-KYC model. |
ekyc_sdk_configuration | String | 4000 | e-KYC SDK Configuration Data only for the SDK e-KYC model. |
ekyc_sdk_secretKey | Object | e-KYC SDK Secret Key data is only for the SDK e-KYC model. |
OCR Analyze ( API 3)
OCR Detection API accepts the ID Document front and back and provides the contents of the ID Document.
API | https://{{baseUrl}}/ekyc/api/v1/efr/ocrDetection |
Authorization | none |
Method | POST |
Headers | Content-Type:application/json |
Payload | {
"ekycRequestId": "<<ekycRequestId>>",
"document": "<<id_document_front_base64>>",
"documentBack": "<<id_document_back_base64>>"
}
|
Success Response Http status Code :200 | {
"status": "string",
"statusCode": 0,
"errorCode": 0,
"message": "string",
"data": {
"success": true,
"transactionId": "string",
"identityCard": {
"frontCardScan": "string",
"backCardScan": "string",
"mrz": {
"line1": "string",
"line2": "string",
"line3": "string"
},
"details": {
"docCode": "string",
"docIssuingAuthority": "string",
"docNumber": "string",
"docExpiryDate": "string",
"docExpiryDateShort": "string",
"primaryIdentifier": "string",
"secondaryIdentifiers": "string",
"dateOfBirth": "string",
"gender": "string",
"nationality": "string",
"registrantNumber": "string"
}
},
"documentIdentifiers": [
{
"docCode": "string",
"docIssuingAuthority": "string",
"docNumber": "string",
"expiryDate": "string"
}
]
}
}
|
Authentication Failure Http status Code :401 | {
"timestamp": "2022-12-05T13:44:31.557+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/api/v1/request"
}
|
Bad Request Http status Code :200 | {
"status": "failure",
"statusCode": 400,
"errorCode": 400,
"message": "ekycRequestId is mandatory"
}
|
e-KYC Request Id not found (Not found) Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 46004,
"message": "eKYC RequestId not found!"
}
|
e-KYC Provider Mismatch (Bad Request) Http status Code :200 | {
"status": "failure",
"statusCode": 400,
"errorCode": 46005,
"message": "eKYC Request associated with different eKYC Provider!"
}
|
e-KYC Request Expired (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46006,
"message": "eKYC Request Expired!"
}
|
e-KYC Request already Failed (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46007,
"message": "eKYC Failed, Initiate new Request!"
}
|
e-KYC Request already Rejected (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46008,
"message": "eKYC Rejected, Initiate new Request!"
}
|
e-KYC Request already Completed (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46009,
"message": "eKYC already Completed!"
}
|
Partner (e-KYC Provider)Service Failure Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 47001,
"message": "EFR eKYC Service is Down!"
}
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | MANDATORY | Content type |
Payload
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
ekycRequestId | String | 54000 | MANDATORY | EKYC Request unique identification number |
document | String | MANDATORY | ID Document Front base 64 data | |
documentBack | String | MANDATORY | ID Document Back base 64 data |
Response
Name | Data Type | Max Length | Description |
|---|---|---|---|
status | String | 255 | status description |
status_code | Integer | - | Status code |
message | String | 255 | Message |
data | Object | - | Data object |
success | Boolean | OCR Detection status | |
transactionId | String | Unique OCR Detection ID | |
identityCard | Object | 255 | ID Card Details |
frontCardScan | String | 4000 | ID Document Front base 64 data |
backCardScan | String | 4000 | ID Document Back base 64 data |
mrz | Object | - | MRZ line Details in the ID Document |
line1 | String | 255 | MRZ Line 1 |
line2 | String | 255 | MRZ Line 2 |
line3 | String | 255 | MRZ Line 3 |
details | Object | ID Card Document Details | |
docCode | String | 255 | ID Document Unique Identification |
docIssuingAuthority | String | 255 | ID Document Issuing Authority |
docNumber | String | 255 | ID Document Number |
docExpiryDate | String | 255 | ID Document Expiry Date |
docExpiryDateShort | String | 255 | ID Document Expiry Date short |
primaryIdentifier | String | 255 | ID Document Primary Identifier |
secondaryIdentifiers | String | 255 | ID Document Secondary Identifier |
dateOfBirth | String | 255 | ID Document Date of Birth |
gender | String | 255 | Gender |
nationality | String | 255 | Nationality |
registrantNumber | Stringeger | 255 | ID Document Registration Number |
documentIdentifiers | Object | Document Identifier | |
docCode | String | 255 | Document Identification Code |
dosccIssuingAuhortys | Boolean | IDDocmnIssgAthoityOCR Detection status | |
dotNmbanacionIr | SringString | ID ocumenNumrUnique OCR Detection ID | |
idexinyDiteyCard | Object | 255 | IDDocumentxpiDID Card Details |
frontCardScan | String | 4000 | ID Document Front base 64 data |
backCardScan | String | 4000 | ID Document Back base 64 data |
mrz | Object | - | MRZ line Details in the ID Document |
line1 | String | 255 | MRZ Line 1 |
line2 | String | 255 | MRZ Line 2 |
line3 | String | 255 | MRZ Line 3 |
details | Object | ID Card Document Details | |
docCode | String | 255 | ID Document Unique Identification |
docIssuingAuthority | String | 255 | ID Document Issuing Authority |
docNumber | String | 255 | ID Document Number |
docExpiryDate | String | 255 | ID Document Expiry Date |
docExpiryDateShort | String | 255 | ID Document Expiry Date short |
primaryIdentifier | String | 255 | ID Document Primary Identifier |
secondaryIdentifiers | String | 255 | ID Document Secondary Identifier |
dateOfBirth | String | 255 | ID Document Date of Birth |
gender | String | 255 | Gender |
nationality | String | 255 | Nationality |
registrantNumber | String | 255 | ID Document Registration Number |
documentIdentifiers | Object | Document Identifier | |
docCode | String | 255 | Document Identification Code |
docIssuingAuthority | String | 255 | ID Document Issuing Authority |
docNumber | String | 255 | ID Document Number |
expiryDate | String | 255 | ID Document Expiry Date |
Face Liveness (API 4)
Face Liveness API is used to check the face liveness of the customer.
API | https://{{baseUrl}}/ekyc/api/v1/efr/faceLiveness |
Authorization | None |
Method | POST |
Headers | Content-Type:application/json |
Payload | {
"ekycRequestId": "<<ekycRequestId>>",
"data": "<<face_data_from_sdk>>"
}
|
Success Response Http status Code :200 | {
"status": "success",
"statusCode": 200,
"data": {
"data": "<<encrypted_face_data_response>>"
}
}
|
Authentication Failure Http status Code :401 | {
"timestamp": "2022-12-05T13:44:31.557+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/api/v1/request"
}
|
Bad Request Http status Code :200 | {
"status": "failure",
"statusCode": 400,
"errorCode": 400,
"message": "ekycRequestId is mandatory"
}
|
e-KYC Request Id not found (Not found) Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 46004,
"message": "eKYC RequestId not found!"
}
|
e-KYC Provider Mismatch (Bad Request) Http status Code :200 | {
"status": "failure",
"statusCode": 400,
"errorCode": 46005,
"message": "eKYC Request associated with different eKYC Provider!"
}
|
e-KYC Request Expired (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46006,
"message": "eKYC Request Expired!"
}
|
e-KYC Request already Failed (Internal Server Error) | {
"status": "failure",
"statusCode": 500,
"errorCode": 46007,
"message": "eKYC Failed, Initiate new Request!"
}
|
e-KYC Request already Rejected (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46008,
"message": "eKYC Rejected, Initiate new Request!"
}
|
e-KYC Request already Completed (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46009,
"message": "eKYC already Completed!"
}
|
Partner (e-KYC Provider)Service Failure Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 47001,
"message": "EFR eKYC Service is Down!"
}
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | MANDATORY | Content type |
Payload
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
ekycRequestId | String | 50 | MANDATORY | EKYC Request unique identification number |
data | String | 4000 | MANDATORY | face data got from sdk |
Response
Name | Data Type | Max Length | Description |
|---|---|---|---|
status | String | 255 | status description |
status_code | Int | - | Status code |
message | String | 255 | Message |
data | Object | - | Data object |
data | String | 4000 | Encrypted face data response |
Confirm Identity (API 5)
The customer's identity is verified using the confirm identity API. The ID document will be validated, and the captured face will be compared to the ID document face.
After the identity has been verified, it will check the initiating agent's e-KYC configuration to see if more data is required to finish e-KYC.
The customer will be onboarded to the customer data platform if additional information is not needed.
API | |
Authorization | None |
Method | POST |
Headers | Content-Type:application/json |
Payload | {
"ekycRequestId": "<<ekycRequestId>>",
"face": {
"data": "<<face_date>>",
"datahash": "Kn3lxsnxI1mFfYV97W6cdYquC0YBDHCeFSYEfoqDk7o=",
"thumbnail": "<<face_thumbnaile_base64_data>>",
"tag": "EFR.2008756088"
},
"identityCard": {
"frontCardScan": "<<id_card_front_base64>>",
"backCardScan": "<<id_card_back_base64>>",
"mrz": {
"line1": "ILARE1070175548784199554586091",
"line2": "9507281M2308027IPD4<<<<1<<<<<1",
"line3": "MUNDACHI<<IRFAN<MANAKKAT<THEKK"
},
"details": {
"docCode": "IL",
"docIssuingAuthority": "ARE",
"docNumber": "107017554",
"docExpiryDate": "2023-08-02",
"docExpiryDateShort": "230802",
"primaryIdentifier": "irfan",
"secondaryIdentifiers": "Thekke",
"dateOfBirth": "950728",
"gender": "M",
"nationality": "ARE",
"registrantNumber": "784199554586091"
}
},
"documentIdentifiers": [
{
"docCode": "IL",
"docIssuingAuthority": "ARE",
"docNumber": "107017554"
}
]
}
|
Success Response if there is no other pending task (ex:- additional information) Customer Onboarded to CDP Http status Code :200 | {
"status": "success",
"statusCode": 200,
"data": {
"confirmation_status": true,
"ecrn": "1058021235161541",
"customer_status": "ACTIVE",
"aml_scan_status": "Accepted"
}
}
|
Success Response if there is pending Task - Customer not onboarded to CDP Http status Code :200 | {
"status": "success",
"statusCode": 200,
"data": {
"confirmation_status": true
}
}
|
Success Response for Identity Mismatch if there is pending Task - Customer not onboarded to CDP Http status Code :200 | {
"status": "success",
"statusCode": 200,
"data": {
"confirmation_status": false,
"rejection_message" :"<<failure message>>"
}
}
|
Authentication Failure Http status Code :401 | {
"timestamp": "2022-12-05T13:44:31.557+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/api/v1/request"
}
|
e-KYC Request Id not found (Not found) Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 46004,
"message": "eKYC RequestId not found!"
}
|
e-KYC Provider Mismatch (Bad Request) Http status Code :200 | {
"status": "failure",
"statusCode": 400,
"errorCode": 46005,
"message": "eKYC Request associated with different eKYC Provider!"
}
|
e-KYC Request Expired (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46006,
"message": "eKYC Request Expired!"
}
|
e-KYC Request already Failed (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46007,
"message": "eKYC Failed, Initiate new Request!"
}
|
e-KYC Request already Rejected (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46008,
"message": "eKYC Rejected, Initiate new Request!"
}
|
e-KYC Request already Completed (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46009,
"message": "eKYC already Completed!"
}
|
Partner (e-KYC Provider)Service Failure Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 47001,
"message": "EFR eKYC Service is Down!"
}
|
Validation Failure Response - Customer Under Compliance Investigation HttpStatusCode : 200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 45013,
"message": "Customer under Compliance investigation!"
}
|
Validation Failure Response - Blocked Customer HttpStatusCode : 200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 45051,
"message": "Customer can not be Accepted"
}
|
Customer Onboarding Failed HttpStatusCode : 200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 47006,
"message": "Customer onboarding failed!"
}
|
CDP Service is Down Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 47006,
"message": "CDP Service is Down!"
}
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | MANDATORY | Content type |
Payload
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
ekycRequestId | String | 50 | MANDATORY | EKYC Request unique identification number |
face | Object | MANDATORY | face Details | |
data | String | 4000 | MANDATORY | face data |
dataHash | String | MANDATORY | data Hash | |
tag | String | MANDATORY | tag | |
thumbnail | String | 4000 | CONDITIONAL | thumbnail portrait of the face captured |
identityCard | Object | MANDATORY | ID Card Details | |
frontCardScan | String | 4000 | MANDATORY | ID Document Front base 64 data |
backCardScan | String | 4000 | MANDATORY | ID Document Back base 64 data |
mrz | Object | - | CONDITIONAL | MRZ line Details in the ID Document |
line1 | String | 255 | CONDITIONAL | MRZ Line 1 |
line2 | String | 255 | CONDITIONAL | MRZ Line 2 |
line3 | String | 255 | CONDITIONAL | MRZ Line 3 |
details | MANDATORY | ID Card Document Details | ||
docCode | String | 255 | MANDATORY | ID Document Unique Identification |
docIssuingAuthority | String | 255 | MANDATORY | ID Document Issuing Authority |
docNumber | String | 255 | MANDATORY | ID Document Number |
docExpiryDate | String | 255 | MANDATORY | ID Document Expiry Date |
docExpiryDateShort | String | 255 | MANDATORY | ID Document Expiry Date short |
primaryIdentifier | String | 255 | MANDATORY | ID Document Primary Identifier |
secondaryIdentifiers | String | 255 | MANDATORY | ID Document Secondary Identifier |
dateOfBirth | String | 255 | MANDATORY | ID Document Date of Birth |
gender | String | 255 | MANDATORY | Gender |
nationality | String | 255 | MANDATORY | Nationality |
registrantNumber | String | 255 | MANDATORY | ID Document Registration Number |
documentIdentifiers | Object | MANDATORY | Document Identifier | |
docCode | String | 255 | MANDATORY | ID Document Issuing Authority |
docIssuingAuthority | String | 255 | MANDATORY | ID Document Issuing Authority |
docNumber | String | 255 | MANDATORY | ID Document Number |
expiryDate | String | 255 | MANDATORY | ID Document Expiry Date |
Response
Name | Data Type | Max Length | Description |
|---|---|---|---|
status | String | 255 | status description |
status_code | Int | - | Status code |
message | String | 255 | Message |
data | Object | - | Data object |
confirmation_status | Boolean | - | e-KYC Confirmation Status |
ecrn (conditional) | String | 20 | CDP Customer Unique Identification Number will be present if customer is onboarded to CDP |
aml_scan_status (conditional) | String | 20 | AML Scanned Status will be p[resent if customer is onboarded to CDP “Accepted” / “Rejected“ / “Under Investigation”/ “Failed” / “N/A” (not available when screening not done) |
customer_status (conditional) | String | 20 | Customer Status will be present if customer is onboarded to CDP ACTIVE / KYC PENDING / INACTIVE / REJECTED / BLOCKED |
rejection_message (conditional) | String | 500 | rejection message will be there if the confirmation status is false |
Provide Additional Information (API 6)
This API is used to provide the customer additional information in order to complete e-KYC, and the customer will be onboarded to CDP if there are no other pending tasks.
API | https://{{baseUrl}}/ekyc/api/v1/additionalInformation/{{ekycRequestId}} |
Authorization | Bearer Token |
Method | POST |
Headers | Content-Type:application/json |
Payload | {
"salutation": "Mr.",
"preferred_name": "Irfan",
"second_nationality": "GB",
"native_region": 1,
"date_of_birth": "19995-03-08",
"country_of_birth": "IN",
"place_of_birth": "Kannur",
"gender": "Male",
"mothers_maiden_name": "Safiya",
"primary_mobile_number": "+971502106707",
"secondary_mobile_number": "+971520210458",
"email_id": "irfanmtp1@gmail.com",
"occupation_id": 10,
"updated_by": "userAbc",
"customer_classification": {
"customer_type_id": 1,
"annual_income_range_id": 5,
"annual_income_currency_code": "AED",
"social_security_number": "SSN123",
"tax_registration_umber": 1234567,
"txn_issued_country": "AE",
"employer_name": "Lulu International Exchange",
"employer_address": "Dubai",
"employer_phone": "+971502106707",
"employer_ecrn": "123456789",
"employer_establishment_id": "30000120",
"group_companies": 1,
"group_employer_code": "786000777",
"personal_mohre_id": "Mohre123",
"income_type": 3,
"profession_category": "PC1",
"reason_for_acc": "Test",
"referred_by_type": 4,
"referred_by": "Irfan",
"txn_vol_month": 2,
"txn_count_month": 2,
"customer_remarks": "test remark",
"show_remarks_on_txn": true,
"agent_ref_no": "ABC1234582",
"first_language": "en",
"marital_status": 1
},
"address_list": [
{
"address_type_id": "1",
"building_name": "ABC Building",
"street_name": "Electra Street",
"landmark": "Landmark",
"city": "DUBAI",
"district": "DUBAI",
"state": "DUBAI",
"country": "AE",
"zip": null,
"po_box": "5379",
"mobile_number": null,
"email_id": null
}
]
}
|
Success Response Http status Code :200 | {
"status": "success",
"statusCode": 200,
"data": {
"ecrn": "1058021235161541",
"customer_status": "ACTIVE",
"aml_scan_status": "Accepted"
}
}
|
Authentication Failure Http status Code :401 | {
"timestamp": "2022-12-05T13:44:31.557+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/api/v1/request"
}
|
Bad Request Http status Code :200 | {
"status": "failure",
"statusCode": 400,
"errorCode": 46022,
"message": " emailId is mandatory in request !"
}
|
e-KYC Request Id not found (Not found) Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 46004,
"message": "eKYC RequestId not found!"
}
|
e-KYC Request Expired (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46006,
"message": "eKYC Request Expired!"
}
|
e-KYC Request already Failed (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46007,
"message": "eKYC Failed, Initiate new Request!"
}
|
e-KYC Request already Rejected (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46008,
"message": "eKYC Rejected, Initiate new Request!"
}
|
e-KYC Request already Completed (Internal Server Error) Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 46009,
"message": "eKYC already Completed!"
}
|
Validation Failure Response - Customer Under Compliance Investigation HttpStatusCode : 200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 45013,
"message": "Customer under Compliance investigation!"
}
|
Validation Failure Response - Blocked Customer HttpStatusCode : 200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 45051,
"message": "Customer can not be Accepted"
}
|
Customer onboarding failed HttpStatusCode : 200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 47006,
"message": "Customer onboarding failed!"
}
|
CDP Service is Down Http status Code :200 | {
"status": "failure",
"statusCode": 500,
"errorCode": 47006,
"message": "CDP Service is Down!"
}
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | MANDATORY | Content type |
Authorization | String | MANDATORY | Authorization Token |
Payload
Mandatory fields may vary based on the e-KYC Provider and agent.
Name | Data Type | Max Length | Description |
|---|---|---|---|
updated_by | String | 255 | Updated User Id |
salutation | String | 3 | Salutation(Mr, Ms) , Salutation Id As per SALUTATION master |
preferred_name | String | 60 | Preferred Name |
second_nationality | String | 2 | Second Nationality code of Customer as per NATIONALITY Master |
native_region | Integer |
| Native Region code asper NATIVE_REGION Master |
date_of_birth | Date |
| Date of Birth in “YYYY-MM-DD” Format |
country_of_birth | String | 2 | Country of Birth code as per COUNTRY Master |
place_of_birth | String | 40 | Place of Birth |
resident_type_id | Long |
| Resident Type Id as per RESIDENT_TYPE Master |
country_of_residence | String | 2 | Resident Country code as per COUNTRY master |
gender | String | 12 | Gender : Male/Female/Other |
mothers_maiden_name | String | 30 | Mothers Name |
primary_mobile_number | String | 20 | Primary Mobile Number |
secondary_mobile_number | String | 20 | Secondary Mobile Number |
email_id | String | 254 | Email Id |
phone_number | String | 20 | Phone Number |
occupation_id | Long |
| Occupation Id as per OCCUPATION master |
addressList | Object |
| Data Object |
address_type_id | Long |
| Address Type Id as per ADDRESS_TYPE master |
building_name | String | 30 | Building Name |
street_name | String | 30 | Street Name |
landmark | String | 30 | Landmark |
country | String | 2 | Country |
state | String | 30 | State |
district | String | 30 | District |
city | String | 30 | City |
zip | Long |
| Zip |
mobile_number | String | 30 | Mobile Number |
status | String | 30 | Disable |
customer_classification | Object |
| Data Object |
customer_type_id | Long |
| Customer Type Id as per CUSTOMER_TYPE master |
income_type |
|
| Income type id as per INCOME_TYPE master |
annual_income_range_id | Long |
| Annual Income Range Id As per ANNUAL_INCOME master |
annual_income_currency_code | String | 30 | Annual Income Currency Code as per CURRENCY master |
social_security_number | String | 30 | Social Security Number |
tax_registration_number | Long |
| Tax Registration Number |
txn_issued_country | String | 2 | Tax Issued Country code as per COUNTRY master |
employer_name | String | 30 | Employer Name |
employer_address | String | 30 | Employer Address |
employer_phone | String | 30 | Employer Phone |
employer_ecrn | String | 30 | Employer ECRN |
employer_establishment_id | String | 30 | Employer Establishment ID |
risk_rating_id | Long |
| Risk Rating ID as per RISK_RATING master |
compliance_category_id | Long |
| Compliance Category ID |
group_companies | Integer |
| Group Company id as per GROUP_COMPANY master |
group_employer_code | String | 30 | Group Employee Code |
personal_mohre_id | String | 30 | Personal Mohre Id |
customer_cards | String | 30 | Customer Cards |
card_number | String | 30 | Card Number |
profession_category | String | 30 | Profession Category |
reason_for_acc | String | 30 | Reason for ACC |
referred_by_type | Integer |
| Referred By Type |
referred_by | String | 30 | Reffered By |
txn_vol_month | String | 30 | Transaction Volume Month |
txn_count_month | String | 30 | Transaction Count Month |
show_remarks_on_txn | Boolean |
| show Remarks on transaction |
customer_remarks | String | 30 | Remarks on Transaction |
agent_ref_no | String | 30 | Agent reference number |
first_language | String | 3 | Customer Preferred Language |
marital_status | Integer |
| Marital Status |
profile_category | Integer |
| Profile Category |
dnfbp | Boolean |
| Designated Non-Financial Business and Professions |
Parameter
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
ekycRequestId | String | 50 | MANDATORY | e-KYC Request Id |
Response
Name | Data Type | Max Length | Description |
|---|---|---|---|
status | String | 255 | status description |
status_code | Int | - | Status code |
data | Object | - | Data object |
ecrn (conditional) | String | 20 | CDP Customer Unique Identification Number if customer is onboarded to CDP |
aml_scan_status (conditional) | String | 20 | AML Scanned Status if customer is onboarded to CDP “Accepted” / “Rejected“ / “Under Investigation”/ “Failed” / “N/A” (not available when screening not done) |
customer_status (conditional) | String | 20 | Customer Status if customer is onboarded to CDP ACTIVE / KYC PENDING / INACTIVE / REJECTED / BLOCKED |
Get Customer Profile (API 7)
API to be used to get the customer information by customer number.
API | |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json |
Payload | None |
Success Response Http status Code :200 | {
"ecrn": "1058021235161541",
"first_name": "IRFAN MANAKKAT THEKKE",
"salutation": null,
"middle_name": "PURAYIL ISMAIL",
"last_name": "NANGARATH MUNDACHI",
"preferred_name": "IRFAN MANAKKAT THEKKE",
"nationality": "IN",
"second_nationality": "GB",
"native_region": 1,
"date_of_birth": "1995-07-28",
"country_of_birth": "IN",
"place_of_birth": "INDIA",
"resident_type_id": 101,
"country_of_residence": "AE",
"gender": "Male",
"mothers_maiden_name": "maiden Name",
"primary_mobile_number": "+971502106707",
"secondary_mobile_number": "+971502106706",
"email_id": "irfanmtp1@gmail.com",
"phone_number": "+971502106705",
"occupation_id": 2856,
"political_exposed_person": false,
"aml_scan_status": "Accepted",
"customer_iban": "AE083141058021235161541",
"customer_status": "ACTIVE",
"aml_category": 5,
"additional_docs": [
{
"contentType": "image/jpeg",
"file_name": "customer/additionalDoc/1058021235161541_1.jpeg"
}
],
"address_list": [
{
"dateUpdated": "2023-03-15T14:34:07.849554Z",
"address_type_id": "1",
"building_name": "MANKHOOL BUILDING",
"street_name": "",
"landmark": "AL NAHDA",
"city": "EMIRATE OF DUBAI",
"district": "",
"state": " ",
"country": "AE",
"zip": 0,
"mobile_number": null
}
],
"id_details": [
{
"dateUpdated": "2023-03-15T14:34:07.849554Z",
"id_type": 2,
"id_number": "P4006315",
"visa_number": "0",
"visa_expiry_date": null,
"name_as_per_id": " ",
"issued_country": "IN",
"issued_by": "INDIA Govt.",
"issued_at": null,
"issued_on": "2016-08-08",
"date_of_expiry": "2026-08-08",
"default_status": true,
"active_status": true,
"id_front": null,
"id_back": null
},
{
"dateUpdated": "2023-03-15T14:34:07.849554Z",
"id_type": 4,
"id_number": "784199554586091",
"visa_number": "0",
"visa_expiry_date": null,
"name_as_per_id": " ",
"issued_country": "AE",
"issued_by": "EIDA",
"issued_at": null,
"issued_on": "2020-08-08",
"date_of_expiry": "2023-08-08",
"default_status": true,
"active_status": true,
"id_front": {
"base64_data": "",
"file_name": "customer/id/1058021235161541_ID_FR_4_784199554586091.jpeg",
"content_type": "image/jpeg"
},
"id_back": null
}
],
"customer_classification": {
"dateUpdated": "2023-02-14T10:28:03.762012Z",
"customer_type_id": 2,
"annual_income_range_id": 15,
"annual_income_currency_code": null,
"social_security_number": null,
"tax_registration_number": null,
"txn_issued_country": null,
"employer_name": "EMKE",
"employer_address": "UAE",
"employer_phone": " ",
"employer_ecrn": "",
"employer_establishment_id": "",
"risk_rating_id": 3,
"last_review_date": null,
"next_review_date": null,
"pep_category": null,
"group_companies": null,
"group_employer_code": " ",
"personal_mohre_id": "",
"income_type": 1,
"profession_category": "",
"reason_for_acc": " ",
"referred_by": "1058021235161541",
"referred_by_type": 1,
"txn_vol_month": 1,
"txn_count_month": 1,
"show_remarks_on_txn": false,
"customer_remarks": "",
"agent_ref_no": null,
"ekyc_provider": null,
"ekyc_ref_no": null,
"customer_cards": null,
"card_number": null,
"social_links": [],
"subscriptions": [
{
"subsciption_type": "PREMIUM",
"subscription_id": "GOLD CARD",
"status": "active"
}
],
"first_language": "",
"marital_status": null,
"dnfbp": false,
"dpms": false,
"profile_category": 1,
"profile_photo_file_name": null
},
"customer_relations": [],
"communication_consents": [
{
"allow": true,
"communication_type": 1
},
{
"allow": true,
"communication_type": 2
}
]
}
|
Customer not found Failure Response Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 45001,
"message": "Customer not found"
}
|
Customer Not Subscribed Failure Response Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 45003,
"message": "Customer not Subscribed"
}
|
Authentication Failure Response Http status Code :401 | {
"timestamp": "2023-03-15T14:26:24.292+00:00",
"status": 401,
"error": "Unauthorized",
"message": "",
"path": "/api/v1/customer/7841001228796988"
}
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | MANDATORY | Content type |
Authorization | String | MANDATORY | Authorization Token |
Parameter
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
ecrn | String | 20 | MANDATORY | Customer unique identification number |
Response
Name | Data Type | Max Length | Description |
|---|---|---|---|
agent_location_id | String | 30 | Agent Location Id |
channel | String | 30 | Channel |
salutation | String | 3 | Salutation(Mr, Ms) |
first_name | String | 30 | First Name |
middle_name | String | 30 | Middle Name |
last_name | String | 30 | Last Name |
preferred_name | String | 30 | Preferred Name |
nationality | String | 2 | Nationality |
second_nationality | String | 2 | Second Nationality of Customer |
native_region | Integer |
| Native Region |
date_of_birth | Date |
| Date of Birth |
country_of_birth | String | 2 | Country of Birth |
place_of_birth | String | 100 | Place of Birth |
resident_type_id | Long |
| Resident Type Id |
country_of_residence | String | 2 | Country of Residence |
gender | Male | 12 | Gender |
mothers_maiden_name | String | 30 | Mothers Name |
primary_mobile_number | String | 30 | Primary Mobile Number |
secondary_mobile_number | String | 30 | Secondary Mobile Number |
email_id | String | 30 | Email Id |
phone_number | String | 30 | Phone Number |
occupation_id | Long |
| Occupation Id |
political_exposed_person | Boolean |
| Political Exposed Person |
additional_docs | Object |
| Data Object |
idNameId | String |
| Id name id |
base64_data | String |
|
|
content_type | String |
| Content Type |
id_details | Object |
| Data Object |
id_type | Long |
| Id Type |
id_number | String | 30 | Id Number |
name_as_per_id | String | 30 | Name as per Id |
issued_country | String | 2 | Issued Country |
issued_by | String | 30 | Issued By |
issued_at | String | 30 | Issued At |
issued_on | Date |
| Issued On |
date_of_expiry | Date |
| Date of Expiry |
visa_number | String | 30 | Visa Number |
visa_expiry_date | Date |
| Visa Expiry Date |
default_status | String | 30 | Default Status |
active_status | String | 30 | Active Status |
id_front | Object |
| Data Object |
base64_data | String |
| Base 64 Data |
content_type | String |
| Content Type |
id_back | Object |
| Data Object |
base64_data | String |
| Base 64 Data |
content_type | String |
| Content Type |
addressList | Object |
| Data Object |
address_type_id | Long |
| Address Type Id |
building_name | String | 30 | Building Name |
street_name | String | 30 | Street Name |
landmark | String | 30 | Landmark |
country | String | 2 | Country |
state | String | 30 | State |
district | String | 30 | District |
city | String | 30 | City |
zip | Long |
| Zip |
mobile_number | String | 30 | Mobile Number |
status | String | 30 | Disable |
customer_classification | Object |
| Data Object |
customer_type_id | Long |
| Customer Type Id |
annual_income_range_id | Long |
| Annual Income Range |
annual_income_currency_code | String | 30 | Annual Income Currency Code |
social_security_number | String | 30 | Social Security Number |
tax_registration_number | Long |
| Tax Registration Number |
txn_issued_country | String | 2 | Tax Issued Country |
employer_name | String | 30 | Employer Name |
employer_address | String | 30 | Employer Address |
employer_phone | String | 30 | Employer Phone |
employer_ecrn | String | 30 | Employer ECRN |
employer_establishment_id | String | 30 | Employer Establishment ID |
risk_rating_id | Long |
| Risk Rating ID |
compliance_category_id | Long |
| Compliance Category ID |
last_review_date | Date |
| Last review Date |
next_review_date | Date |
| Next Review Date |
pep_category | Integer |
| Pep Category |
group_companies | Integer |
| Group Company |
group_employer_code | String | 30 | Group Employee Code |
personal_mohre_id | String | 30 | Personal Mohre Id |
customer_cards | String | 30 | Customer Cards |
card_number | String | 30 | Card Number |
income_type | String | 30 | Income Type |
profession_category | String | 30 | Profession Category |
reason_for_acc | String | 30 | Reason for ACC |
referred_by_type | Integer |
| Referred By Type |
referred_by | String | 30 | Reffered By |
txn_vol_month | String | 30 | Transaction Volume Month |
txn_count_month | String | 30 | Transaction Count Month |
show_remarks_on_txn | Boolean |
| show Remarks on transaction |
customer_remarks | String | 30 | Remarks on Transaction |
agent_ref_no | String | 30 | Agent reference number |
ekyc_provider | String | 30 | ekyc provider |
ekyc_ref_no | String | 30 | ekyc ref number |
social_links | Object |
| Data Object |
social_links_id | Long |
| Social Link Id |
text_field | String | 30 | Text Field |
subscriptions | Object |
| Data Object |
subsciption_type | String | 30 | Subscription Type |
subscription_id | String | 30 | Subscription Id |
status | String | 30 | Status |
first_language | String | 3 | Customer Preferred Language |
marital_status | Integer |
| Marital Status |
profile_category | Integer |
| Profile Category |
dnfbp | Boolean |
| Designated Non-Financial Business and Professions |
dpms | Boolean |
| Dealers in Precious Metals and Stones |
Call Back API for Web Model
For Web Model, partner will provide a callback API with the below structure for updating the response based on the eKYC status.
Payload
{
"confirmation_status": true,
"rejection_message" :"<<failure message if confirmation status is false>>"
"ecrn": "1058021235161541",
"customer_status": "ACTIVE",
"aml_scan_status": "Accepted"
}
eKYC success or failure is identified based on the confirmation_status.
If there are no other pending tasks, like additional information collection, customer will be onboarded to CDP and customer number, customer status and AML scan status will be provided.
If confirmation message status is false, then the rejection message will be updated with the actual rejection reason.
Details
Name | Data Type | Max Length | Description |
|---|---|---|---|
confirmation_status | Boolean | - | e-KYC Confirmation Status |
ecrn (conditional) | String | 20 | CDP Customer Unique Identification Number will be present if customer is onboarded to CDP |
aml_scan_status (conditional) | String | 20 | AML Scanned Status will be p[resent if customer is onboarded to CDP “Accepted” / “Rejected“ / “Under Investigation”/ “Failed” / “N/A” (not available when screening not done) |
customer_status (conditional) | String | 20 | Customer Status will be present if customer is onboarded to CDP ACTIVE / KYC PENDING / INACTIVE / REJECTED / BLOCKED |
rejection_message (conditional) | String | 500 | rejection message will be there if the confirmation status is false |
EFR integration documents:
https://drive.google.com/drive/folders/1GvjUA6rQHHI5yLT5m1c2F_BbHp-lh3Hj?usp=drive_link
Master Data
ADDITIONAL_DOCUMENT
Additional Document Id | Additional Document |
1 | Visa |
2 | KYC Provider Certificate |
3 | ID Issued Authority Certificate |
SALUTATION
Salutation Id | Salutation |
Dr | Doctor |
Mr | Mister |
Mrs | Missis |
Ms | Miss |
Mx | Mix |
ADDRESS TYPE
Address Type Id | Address Type |
1 | Resident Address |
2 | Permanent Address |
MARITAL STATUS
Marital Status Id | Marital Status |
1 | Married |
2 | Single |
Profession Category
Profession Category Id | Profession Category |
PC1 | Salaried |
PC2 | Self Employed |
PC3 | Business |
PC4 | Unemployed |
Referred By
Referred By Id | Referred By |
1 | Walk-In |
2 | Relationship Manager |
3 | Staff |
4 | Customer |
Relation
Relation Id | Relation |
1 | Self |
2 | Mother |
3 | Guardian |
4 | Father |
8 | Wife |
16 | Husband |
32 | Friend |
64 | Colleague |
128 | Employee |
512 | Brother |
1024 | Sister |
Resident Type
Resident Type Id | Resident Type |
100 | NON-RESIDENT |
101 | RESIDENT |
102 | GCC NATIONALITY |
103 | SEAMEN |
104 | DIPLOMATS |
105 | TRANSIT |
109 | TOURIST/VISIT VISA |
Social Link
Social Link Id | Social Link |
1 | |
2 | |
3 | |
4 | |
5 | |
6 |
Transaction Volume
Transaction Volume Id | Transaction Volume |
1 | 0-1000 |
2 | 1001-3000 |
3 | 3001 - 6000 |
4 | 6001 - 30000 |
5 | 30001 - 50000 |
6 | 50001 - 100000 |
7 | 100001 - 250000 |
8 | 250001 - 500000 |
9 | 500001 - 1000000 |
10 | 1000001- 999999999 |
Transaction Count
Transaction Count Id | Transaction Count |
1 | 1 - 4 |
2 | 5 - 10 |
3 | 11 - 20 |
4 | 21 - 30 |
5 | 31 - 40 |
6 | 41 - 50 |
7 | 51 - 100 |
0 Comments