Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 23 Current »

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

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.

image-20240828-102916.png

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.

image-20240828-103349.png

EFR WEB SDK and EFR WEB SDK integration sample project:

https://drive.google.com/file/d/14vquYOenwLFjcSJ2-XmVqPxgZ3QUSTea/view?usp=sharing 

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.

image-20240828-103156.png

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

https://{{baseUrl}}/ekyc/api/v1/request

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

https://{{baseUrl}}/ekyc/api/v1/efr/confirmIdentity

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!"
}

Customer not Residing in the country

HttpStatusCode : 200

{
    "status": "failure",
    "statusCode": 500,
    "errorCode": 45004,
    "message": "Customer is currently not in the country!""
}

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

https://{{baseUrl}}/caas/api/v2/customer/{{ecrn}}

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

Facebook

2

Twitter

3

Linkedin

4

Google

5

Instagram

6

WhatsApp

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

  • No labels

0 Comments

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account.