Partner EKYC Journey [EFR] - V3
Version History:
Version | Description | Author | Date (dd/mm/yyyy) |
1.0.0 | DRAP eKYC Journey [EFR] Document | Ajai Antony | 07/06/2024 |
1.0.1 | Update on various model description and sequence diagram | Ajai Antony | 28/08/2024 |
1.0.2 | New error code (45004) included under Confirm Identity (API 5) | Ajai Antony | 29/08/2024 |
1.0.3 | Included AML CallBack API | Ajai Antony | 15/10/2024 |
1.0.4 | Web HTML Model deprecated & removed | Ajai Antony | 20/02/2025 |
1.0.5 | Included description of the error codes, the reason for the response, and the recommended steps for resolution. | Ajai Antony | 23/05/2025 |
1.0.6 | Call Back API for Web Model deprecated & removed | Ajai Antony | 21/08/2025 |
1.0.7 | Customer Onboarding Status details | Ajai Antony | 14/10/2025 |
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 SDK Model
Mobile SDK Model
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.
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 | Reason / Next Step | |
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"
} | Provide mandatory fields and retry. |
Failure Response e-KYC not Configured Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 46001,
"message": "eKYC not Configured for the Agent!"
} | Contact Support team to configure the eKYC for the Agent. |
Failure Response Invalid e-KYC Provider Http status Code :200 | {
"status": "failure",
"statusCode": 404,
"errorCode": 46002,
"message": "Invalid eKYC Provider"
} | Pass correct 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!"
} | Provided eKYC model is not supported by the eKYC provider. Pass correct eKYC model for the 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"
} | Token is expired or not provided. Pass valid authentication token. |
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!"
} | Contact Support team. Retry after sometime. |
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 | Reason / Next Step |
Authorization | none |
|
Method | POST |
|
Headers | Content-Type:application/json |
|
Payload | {
"ekycRequestId": "<<ekycRequestId>>",
"document": "<<id_document_front_base64>>",
"documentBack": "<<id_document_back_base64>>"
} |
|
Success Response |