KYC Use Cases
This section describes the concepts of KYC and KYB and the extensible Eclipse KYC/B framework. Additional KYC/B information is available in the KYC FAQs and the following use cases:
- Register a New Customer with a Digital Wallet
- Register a New Customer and Issue a Virtual Card
- Register a New Customer and Issue a Physical Card
Know Your Customer (KYC)
Know Your Customer (KYC) is a company’s regulatory obligation to combat financial crime by verifying the identity of individual customers to curb financial crimes like money laundering.
Know Your Business (KYB)
Similar to KYC, Know Your Business (KYB) is part of a company’s obligation to verify the identity of business customers. As part of their Anti-Money Laundering (AML) programs, financial institutions are obliged to perform KYC and KYB checks. Customers' identities must be verified by businesses to prevent them from aiding money launderers, identity thieves, people on sanctions lists, or any other financial crimes.
Typical Required KYC/KYB Data
The required minimum KYC and KYB data will vary based on the regulatory requirements of the region and sponsoring bank, however, the following are the most typical base data KYC and KYB requirements:
Typical Required KYC Data
- Full Name - must be as on the client’s selected identity document.
- Mobile Number - OTP is sent to the provided mobile number for verification.
- Proof of identity could be a National ID, a Valid Passport, or an Asylum Reference Number. The information on the uploaded identification will be extracted through OCR (optical character recognition). The extracted information will now be compared with what was captured by the user during onboarding.
- Selfie - must match the client’s image on their Identification document.
- Proof of Address - the customer will have to capture their address details before they can create a physical or virtual card. Additional details required by the TPS include gender and date of birth.
- The client might have to pass these checks: UN, OFAC, PEP, and Match check(AML)
Typical Required KYB Data
- Profile data - company name, organization type, business type.
- Business Address.
- Documents e.g. certificate of incorporation/registration, business license, tax document, etc.
- Positions - existing individual clients can be added to a corporate client’s profile.
Typical KYC Process
The KYC process involves the following steps:
- Create customer and gatherer profile information.
- Gather customer documentation - optionally perform OCR and validate during upload.
- Validate provided profile information and documentation as per KYC/B configuration - e.g. ensure names match documents, and facial match is positive across selfies and identity documents.
- Validate provided profile information and provided documentation against trusted 3rd party providers - e.g. SecureCitizen in South Africa or Integrated Population Registration System (IPRS) in Kenya.
- Perform AML checks e.g. internal deny list, UN/OFAC/UK sanctions list, PEP, MATCH.
- Based on provided information and tests risk score is calculated and wallets that can be provisioned are determined.
Manual KYC Verification
Certain tenants may want to introduce a mandatory KYC verification step where authorized staff review and validate user-provided details before a wallet can be set to ACTIVE. In this scenario admin users ensure the accuracy and legitimacy of information and documents before making decisions on accepting or rejecting a KYC application.
To support this a KYC ruleset is required to enable wallets in a BARRED state for the tenant after automated KYC verification has been complete. This facilitates the utilization of the KYC Verification functionality.
Functionality Usage:
- Admin users navigate to the KYC Verification functionality.
- Access the global verification screen to filter applications by status (Pending, Accepted, Rejected).
- Apply date-based searches or utilize the ratify result ID for specific application searches.
- Review applications, verify KYC checks, add comments, and update application status.
- Actions, like Approve, Reject, or Leave in a Pending status, are available based on admin decision.
- Admins can change status at any stage, which affects wallet states (BARRED/UNBARRED).
Refer to KYC Verification in the Admin Portal Guide for detailed instructions on enabling, configuring, and utilizing this functionality.
Customer Onboarding and Wallet/Card Provisioning
During onboarding, customers will be prompted to capture the minimum KYC/KYB information required for them to be eligible for a particular wallet.
- This will include the client's biodata and KYC documents. KYC documents include identification documents (national identity, passport, asylum permit), facial photo, and proof of address.
- Once all required information is provided and submitted, the client’s profile will be created with the customer ID.
- The created customer profile will be ratified based on the tenant’s KYC rulesets. This will kick off the various checks and algorithms in Eclipse to analyze the customer profile, address, and attached documents to update the customer's KYC status. This call will return detailed results of the KYC process such as what passed and what failed in the various tests. The customer profile can be updated along with addresses and documents and ratified again until the required KYC status for the wallet type is obtained. The wallet type determines what level of KYC is required for a customer/organization to own that type of wallet.
- A user can always determine what wallets can be provisioned based on the provided KYC/B information by calling the wallet-types endpoint for the customer or the organization.
- If the user has opted for a digital wallet then a digital wallet will be created and linked to the customer’s profile. In this case, the WalletTypeId must be of a type for a digital wallet mode. - refer to this documentation.
- If the user opts for a virtual card, then a digital wallet will be created which will also automatically create and link a virtual card to the digital wallet. In this case, WalletTypeId must be of a type for mode PREPAID_CARD - refer to this documentation.
- If the customer opts for a physical card, depending on the card packaging, either the PAN, Pack ID, or Card QR code will be used to register the physical card. In this case, WalletTypeId must be for a card mode. - refer to this documentation.
Document OCR and Validation
An important part of KYC/B is uploading supporting documents. For the list of supported document types please refer to the documents endpoint.
When KYC/B is performed Optical Character Recognition (OCR) is run on the documents and document validation is run. We recommend that this be done when uploading the documents and not only when KYC is performed - this allows an enhanced onboarding journey where invalid documents can be detected as they are uploaded and not only at the end of the onboarding journey when KYC is performed.
To do this query parameters performOcr and validateDocType should be set to true:
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/documents?performOcr=true&validateDocType=true
Passport data extraction
One of the most common KYC document types as a means to identify individuals is PASSPORT. Passports globally contain a standardised Machine Readable Zone (MRZ) that can be parsed and information extracted. Eclipse supports this data extraction and if query parameter performOcr is set to true when uploading a passport document the extracted structured information is returned in the extraInfo field of the response. This allows an enhanced onboarding journey for passport documents where the following information can be extracted from the passport and does not need to be entered by the customer:
- Passport number
- Expiry date
- Birth date
- First name
- Last Name
- Sex
- Nationality
Prerequisites:
- When uploading the passport document, the query parameter performOcr is set to true.
- Tenant config ratifyUserProcessors includes: firstNameMatchesPassport=AsyncGenericPassportProcessorUsingAzureWithNoDependency,lastNameMatchesPassport=AsyncGenericPassportProcessorUsingAzureWithNoDependency,passportNumberMatchesPassport=AsyncGenericPassportProcessorUsingAzureWithNoDependency,passportIsLegitimate=AsyncGenericPassportProcessorUsingAzureWithNoDependency,isPassportExpiryDateMatch=AsyncGenericPassportProcessorUsingAzureWithNoDependency,dateOfBirthMatchesPassport=AsyncGenericPassportProcessorUsingAzureWithNoDependency,issueDateMatchesPassport=EmptyItemProcessor
The structured information is returned in the extraInfo field under azureResult - an example response is:
{
"azureResult": {
"passportNumber": "M00000001",
"expiryDate": "20190329",
"birthDate": "19800101",
"firstName": "JANE",
"lastName": "SPECIMEN",
"sex": "F",
"nationality": "SOUTH AFRICAN / SUD-AFRICAINE",
"ocrContent": "Passport / PasseportnREPUBLIC OF SOUTH AFRICA / REPUBLIQUE D'AFRIQUE DU SUDnType / TypenCountry code / Code du paysnPassport No / No du passeportnPMnZAFnM00000001nSurmame / NomnSPECIMENnGiven names / PrénomsnJANEnNationality / NotionainonSOUTH AFRICAN / SUD-AFRICAINEnDate of birth / Date de naissancenZAFSAn01 JAN 1980n8001014999082n12120nSou / SeannFnZAFnAuthority /Autoritén30 MAR 2009nDEPT OF HOME AFFAIRSnDate of expiry / Date d'arpiradon29 MAR 2019nJ. SpecimennPMZAFSPECIMEN << JANE <<<<<<<<<<<<<<<<<<<<<<<<<nM000000015ZAF8001014F19032908001014999082<30"
}
}
Liveness Detection
An important aspect of KYC and identity verification is to determine whether the onboarding user is a live human being. This typically involves providing a facial photo or video stream of the users face where a facial image can then be extracted and compared with supporting documentation or 3rd parties.
Eclipse ratifty items related to liveness are:
- selfieIsLegitimate - this verifies that the provided biometric is a valid proof of liveness
- selfieMatchesNationalIdentity, selfieMatchesPassport, selfieMatchesNationalDatabase, selfieMatchesAsylumPaper - these verify that the facial image in the provided biometric matches supporting documents or a 3rd party source (e.g. the South African Home Affairs database).
Eclipse supports static liveness test with a selfie image as well as AWS liveness detection that uses video streaming.
Note
For any new KYC integrations we suggest using AWS Liveness for liveness detection due to its capabilities in terms of fraud prevention.
AWS Liveness Detection
In this scenario the AWS Liveness detection service is used to ensure the liveness of the user through a video stream where the user is prompted and must follow directions. AWS Liveness uses AI and other sophisticated techniques to confirm liveness and prevent fraud. For further details on AWS Liveness detection please refer to AWS documentation.
Tenants have 2 integration options when using AWS Liveness detection in Eclipse:
- Eclipse Hosted AWS Liveness - in this scenario tenants only need to serve a web view hosted by Eclipse to complete the liveness detection
- AWS SDK Integration - integrate directly to the AWS SDK - this allows you to do native integration using the AWS Amplify SDK
Pre-requisites
- Valid JWT
- Tenant config ratifyUserProcessors includes selfieIsLegitimate=AWSLivenessRatifyProcessor
Request AWS Session ID
An AWS session ID can be requested by calling the documents endpoint and passing FACIAL_PHOTO as the documentType and aws/liveness as the mediaType.
If the tenant is using the Eclipse Hosted AWS Liveness option, a landingUrl needs to be passed in the extraInfo field. This URL defines where where the customers iFrame/Browser should be navigated to after the AWS liveness check has completed. When this is a provided a completionUrl will be provided in the extraInfo field in the response.
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/documents?performOcr=false&validateDocType=false
{
"documentType" : "FACIAL_PHOTO",
"mediaType" : "aws/liveness",
"extraInfo" :"{\"landingUrl\":\"https://react-aws-liveness-sandbox.ukheshe.rocks/callback\"}"
}
Example response:
{
"documentId": 608561,
"documentType" :"FACIAL_PHOTO",
"customerId" :1592544,
"base64EncodedDocument" :"YXdzTGl2ZW5lc3NTZXNzaW9uSWQ9ZTY0ZTY0MmItZjhkYi00OTliLWIzZjEtZGIxMGYzMTAwMzg3",
"mediaType" :"aws/liveness",
"created" :"2024-04-08T11:46:29.000Z",
"lastModified" : "2024-04-08T11:46:29.000Z",
"version" :0,
"extraInfo": "{\"landingUrl\":\"https://react-aws-liveness-sandbox.ukheshe.rocks/callback\",\"awsLivenessSessionId\":\"e64e642b-f8db-499b-b3f1-db10f3100387\",\"completionUrl\":\"https://eclipsetests.backdraft.ukheshe.rocks/t/wXExW\"}",
"isHistoricalDocument" : "false",
"awsFaceLivenessSessionId" : "e64e642b-f8db-499b-b3f1-db10f3100387"
}
Note
- The AWS session ID expires 3 minutes after it has been issued.
- The base64EncodedDocument field is populated with the following base64 encoded data:
awsLivenessSessionId={awsLivenessSessionId}
Eclipse Hosted AWS Liveness
To utilise Eclipse Hosted AWS Liveness, tenants need to provide a landingUrl as part of the extraInfo field when requesting a session ID as described above. A completionUrl is returned and the tenant needs to serve that URL in a web view and the rest is managed by Eclipse.
Callback status
Eclipse Hosted AWS will return the following status' when navigating back to the landingUrl
- {landingUrl}?status=CANCELLED - in the event of any error or the user cancels the session
- {landingUrl}?status=COMPLETED - in the case of successful completion of AWS Liveness validation
Custom Branding
The Eclipse Hosted AWS portal can be branded with a tenant's corporate colors and logo by setting attributes in global property public.tenant.{tenantId} property. Please refer to this documentation on how to customise the branding for the AWS hosted portal.
AWS SDK Integration
To integrate directly to the AWS SDK tenants must utilise the AWS Amplify framework. The AWS Amplify UI FaceLivenessDetector provides a UI component for Amazon Rekognition Face Liveness that helps developers verify that only real users, not bad actors using spoofs, can access your services. For full integration details please refer to the AWS documentation.
Note
When initialising the AWS Amplify SDK you must use an Ukheshe provided configuration file.
For sandox you can retrieve the following property using the get property endpoint:
- public.jwt.protected.aws.amplify.config.sandbox for sandbox.
- public.jwt.protected.aws.amplify.config.live for production.
These properties are available to any Eclipse user with a JWT.
When adding the FaceLivenessDetector you should pass it the session ID retrieved from Eclipse in the previous step.
Update the FACIAL_PHOTO document with AWS Liveness results
Once you have completed the liveness process either using the hosted liveness option or the AWS SDK integration you need to update the FACIAL_PHOTO document that was created when retrieving the AWS Session ID above. This document update triggers Eclipse to retrieve information from AWS including the liveness result, the liveness score and a facial image taken during the video stream, and storing it on the document object. The AWS liveness result and score are included in the extraInfo field of the reponse:
PUT /eclipse-conductor/rest/v1/tenants/{tenantId]/documents/{documentId}?returnFullResult=false
{
"documentId": 608561,
"documentType" :"FACIAL_PHOTO",
"customerId" :1592544,
"base64EncodedDocument" :"YXdzTGl2ZW5lc3NTZXNzaW9uSWQ9ZTY0ZTY0MmItZjhkYi00OTliLWIzZjEtZGIxMGYzMTAwMzg3",
"mediaType" :"aws/liveness",
"created" :"2024-04-08T11:46:29.000Z",
"lastModified" : "2024-04-08T11:46:29.000Z",
"version" :0,
"extraInfo": "{\"landingUrl\":\"https://react-aws-liveness-sandbox.ukheshe.rocks/callback\",\"awsLivenessSessionId\":\"e64e642b-f8db-499b-b3f1-db10f3100387\",\"completionUrl\":\"https://eclipsetests.backdraft.ukheshe.rocks/t/wXExW\"}",
"isHistoricalDocument" : "false",
"awsFaceLivenessSessionId" : "e64e642b-f8db-499b-b3f1-db10f3100387"
}
Example response:
{
"documentId" : 608561,
"documentType" : "FACIAL_PHOTO",
"customerId" : 1592544,
"mediaType" : "image/jpeg",
"created" : "2024-04-08T11:46:29.000Z",
"lastModified" : "2024-04-08T11:46:29.135Z",
"version" : 2,
"extraInfo" : "{\"landingUrl\":\"https://react-aws-liveness-sandbox.ukheshe.rocks/callback\",\"awsLivenessSessionId\":\"e64e642b-f8db-499b-b3f1-db10f3100387\",\"completionUrl\":\"https://eclipsetests.backdraft.ukheshe.rocks/t/wXExW\",\"AwsFaceLivenessResult\":\"SUCCEEDED\",\"AwsFaceLivenessScore\":\"75.7301250000000010231815394945442676544189453125\"}",
"isHistoricalDocument" : "false"
}
Whether the AWS Liveness result is successful or unsuccessful is determined by the confidence score AWS returns for the session ID. By default a confidence score higher than 55 is considered successful. This can be controlled by setting tenant config aws.face.liveness.ConfidenceScoreMin.
The final step, done as part of the end to end KYC process is to run the KYC algorithm by calling the ratify endpoint.
Suggested prompts when using AWS liveness detection:
The AWS Amplify components control the UI displayed, however it is recommended that customers are guided to:
- Position their face within the oval shape
- Click the Start Video check button to begin
- Folllow on screen instructions to complete the process
Note
There are very few scenarios where a liveness check has been successfully completed and it needs to be redone. As an example - if KYC does not pass due to other tests fails, you should NOT initiate a new AWS liveness test. Rather redo only the part of the KYC relevant to the failures, e.g. capturing customer information and documents. As there are 3rd party costs involved excessive liveness tests conducted for the same customer will incur tenant charges.
Static Liveness Detection
In this scenario a document uploaded of type FACIAL_PHOTO is checked to confirm that it has a facial image in it as well as a thumbs up: a thumbs up selfie.
The uploaded image is analysed using AI to find recognised objects and artifacts. The result of this analysis is stored against the image once it is analysed. Its in the form “label”:
<probability %>.
The selfieIsLegitimate checks are configurable but currently are set as follows:
- “Thumbs Up” score of >=35% or a “Finger” >=60%
- “Text” <90% and “Book” < 50% and “Drawing” < 50%
Pre-requisites
- Valid JWT
Upload a document of type FACIAL_PHOTO and include the image as base64 encoded in the base64EncodedDocument field:
POST /eclipse-conductor/rest/v1/tenants/7671/customers/640879/documents?performOcr=true&validateDocType=true
{
"base64EncodedDocument" : "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHB",
"documentType": "FACIAL_PHOTO",
"isOcrChecked" : true,
"isValidateDocTypeChecked" : true,
"mediaType" : "image/jpeg"
}
{
"documentId": 1011589,
"documentType": "FACIAL_PHOTO",
"customerId": 640879,
"mediaType": "image/jpeg",
"created": "2024-01-16T14:01:40.000Z",
"lastModified": "2024-01-16T14:01:40.000Z",
"version": 0,
"extraInfo": "{\"Long Sleeve\":50.3466,\"T-Shirt\":83.72749,\"Electronics\":99.07532,\"Sweatshirt\":50.99504,\"Male\":98.86403,\"Jewelry\":52.171165,\"Mustache\":51.34559,\"Furniture\":53.851624,\"Sleeve\":50.3466,\"Goggles\":52.098537,\"Shirt\":54.416664,\"Curtain\":50.41236,\"Potted Plant\":51.502045,\"Desk\":51.271255,\"Coat\":56.974228,\"Head\":99.99977,\"Jacket\":56.974228,\"Architecture\":53.851624,\"Clothing\":83.72749,\"Body Part\":100.0,\"Cushion\":51.246696,\"Smile\":50.694553,\"Hand\":100.0,\"Sunglasses\":55.88755,\"Blazer\":52.174377,\"Headphones\":99.07532,\"Glasses\":99.99906,\"Man\":98.86403,\"Person\":100.0,\"Building\":53.851624,\"Knitwear\":55.053402,\"Sitting\":52.304184,\"Studio\":51.428394,\"Wrist\":54.345734,\"Accessories\":99.99906,\"Plant\":51.502045,\"Bedroom\":50.74664,\"Adult\":98.86403,\"Face\":99.99977,\"Room\":53.851624,\"Bed\":50.74664,\"Floor\":51.434006,\"Table\":51.271255,\"Wristwatch\":50.98955,\"Happy\":50.694553,\"Finger\":100.0,\"Portrait\":99.99977,\"Couch\":52.500336,\"Selfie\":54.967064,\"Photography\":99.99977,\"Indoors\":62.312363,\"Sweater\":55.053402,\"Hoodie\":50.99504,\"Home Decor\":54.155983,\"Ring\":52.171165,\"Living Room\":53.851624,\"Interior Design\":53.55351,\"Thumbs Up\":57.9648}",
"isHistoricalDocument": false
}
Note
- If performOcr=true when posting the document, then the image analysis is done immediately and the response is returned in the extraInfo field
- If isValidateDocTypeChecked=true when posting the document, the API call will fail if the document is not valid
Suggested prompts when using static liveness:
For full details please refer to FAQ Suggested prompts to aid successful KYC.
For facial photos that require a static liveness check, the customer should ensure that the photo is taken in front of a plain, light coloured wall and both the face and hand with thumbs up are clear and visible and completely contained in the frame:
KYC/KYB Rulesets and Ratify Items
Ratify is initiated on the system to verify and validate the customer’s details i.e., both individual and businesses. The process is driven by KYC/KYB rulesets and KYC ratify items configured on Eclipse.
A ruleset can be defined as part of a wallet type configuration - therefore a client would have to meet the requirements specified in the ruleset to be able to provision a particular wallet type.
The foundation of Eclipse’s KYC/KYB framework lies in a robust set of ratify items that can be combined into rulesets. KYC ratify items include things like
- A liveness check on the provided selfie
- A facial match check confirming the provided selfie and national identity match
- A third party check to confirm the provided details align with a trusted third party like Secure Citizen in South Africa or the Integrated Population Registration System (IPRS) in Kenya
Eclipse supports the following ratify items:
Ratify Item | Type (OCR/ Compliance) | Description |
---|---|---|
selfieIsLegitimate | OCR | Liveness check on the provided selfie. |
selfieMatchesNationalIdentity | OCR | Verify if the selfie uploaded to the customer’s profile matches the facial image on the national identity document. |
firstNameMatchesNationalIdentity | OCR | Verify if the first name on the customer’s profile matches the first name on the national identity document. |
lastNameMatchesNationalIdentity check | OCR | Verify if the last name on the customer’s profile matches the last name on the national identity document. |
identityNumberMatchesNationalIdentity | OCR | Verify if the national ID number on the customer’s profile matches the ID number on the national identity document. |
selfieMatchesPassport | OCR | Verify if the selfie uploaded to the customer’s profile matches the facial image on their passport. |
firstNameMatchesPassport | OCR | Verify if the first name on the customer’s profile matches the first name on their passport. |
lastNameMatchesPassport | OCR | Verify if the last name on the customer’s profile matches the last name on their passport |
passportNumberMatchesPassport | OCR | Verify if the passport number on the customer’s profile matches the passport number on their passport. |
addressMatchesProofOfAddress | OCR | Verify if the address details on the client’s profile match the uploaded proof of address document. |
pepCheck | Compliance | Check whether User are on the Politically exposed persons List NOTE: Only available in South Africa |
selfieMatchesNationalDatabase | Compliance | Check whether the Selfie taken matches the National Database photo |
matchCheck | Compliance | Mastercard Alert To Control High-risk Merchants (MATCH) lets an acquiring partner look up whether another acquiring partner has terminated a merchant in the past and the reason for said termination |
passportIsLegitimate | OCR | Verify if an uploaded passport document is legit. |
isPassportExpiryDateMatch | OCR | Verify the passport expiry date added to the customer profile with the expiry date on their passport. |
nationalIdentityIsLegitimate | OCR | Verify if an uploaded identification document is legit. |
firstNameMatchesAsylumPaper | OCR | Verify if the first name on the customer’s profile matches the first name on the asylum paper. |
lastNameMatchesAsylumPaper | OCR | Verify if the last name on the customer’s profile matches the last name on the asylum paper. |
dateOfBirthMatchesAsylumPaper | OCR | Verify if the date of birth on the customer’s profile matches the date of birth on the asylum paper. |
selfieMatchesAsylumPaper | OCR | Verify if the selfie uploaded to the customer’s profile matches the facial image on their asylum paper. |
asylumPaperRefNumberMatchesAsylumPaper | OCR | Verify if the asylum reference number on the customer’s profile matches the reference number on the asylum document. |
asylumPaperIsLegitimate | OCR | Verify if the asylum paper is legit. |
firstNameMatchesBirthCertificate | OCR | Verify if the first name on the customer’s profile matches the first name on their birth certificate. |
lastNameMatchesBirthCertificate | OCR | Verify if the last name on the customer’s profile matches the last name on their birth certificate. |
isDateOfBirthMatchesBirthCertificate | OCR | Verify if the date of birth on the customer’s profile matches the date of birth on their birth certificate. |
taxNumberMatchesTaxDocument | OCR | Verify the Tax number added to the customer profile with the uploaded ‘TaxDocument’ |
firstNameMatchesTaxDocument | OCR | Verify the First name added to the customer’s profile with the uploaded “TaxDocument” |
lastNameMatchesTaxDocument | OCR | Verify the Last name added to the customer’s profile with the uploaded “TaxDocument” |
iprsCheck | Compliance | Verify the national ID added to the customer’s profile against the Kenyan Integrated Population Registration System (IPRS). |
customListKycCheck | Compliance | DEPRICATED |
internalBlackListCheck | Compliance | Allows Organisations to keep their own Black List of Customers |
ukCheck | Compliance | Check UK Sanctions List |
ofacCheck | Compliance | Check for Office of Foreign Assets Control - Economic and trade sanctions based on US foreign policy and national security goals against targeted foreign countries and regimes, terrorists, international narcotics traffickers, etc. |
unCheck | Compliance | Check UN Sanctions List |
secureCitizenCheck | Compliance | Citizen & Credit Check NOTE: Only available in South Africa |
bankStatementIsLegitimate | OCR | Verify if the bank statement is legit. |
nameMatchesVerifiedBankStatement | OCR | |
firstNameMatchesForeignCertificate | OCR | Verify the First name added to the customer profile with the uploaded ‘ForeignCertificate’ |
lastNameMatchForeignCertificate | OCR | Verify the Last name added to the customer profile with the uploaded ‘ForeignCertificate’ |
dateOfBirthMatcheForeignCertificate | OCR | Verify date of Birth added in customer profile with uploaded ‘ForeignCertificate’ |
usaWNineIsLegitimate | OCR | The letters “W-9” must be found on the uploaded document type 'usaw9' |
backOfNationalIdentityIsLegitimate | OCR | Verify if the back of the national identity document is legit. |
serialNumberMatchesBackOfNationalIdentity | OCR | Verify the serial number on the customer’s profile matches the back of their national identity document. |
idNumberMatchesBackOfNationalIdentity | OCR | Verify the ID number on the customer’s profile matches the back of their national identity document. |
nameMatchesBackOfNationalIdentity | OCR | Verify the name on the customer’s profile matches the back of their national identity document. |
dateOfBirthMatchesBackOfNationalIdentity | OCR | Verify the date of birth on the customer’s profile matches the back of their national identity document. |
sexMatchesBackOfNationalIdentity | OCR | Verify the gender on the customer’s profile matches the back of their national identity document. |
issueDateMatchesBackOfNationalIdentity | OCR | Verify the national ID issue date on the customer’s profile matches the back of their national identity document. |
dateOfBirthMatchesPassport | OCR | Verify date of birth on the customer’s profile matches the passport. |
dateOfBirthMatchesNationalIdentity | OCR | Verify date of birth on the customer’s profile matches the national identity document. |
isAsylumPaperExpiryDateMatch | OCR | Verify asylum expiry date on the customer’s profile matches the asylum paper. |
taxDocumentIsLegitimate | OCR | Verify the uploaded tax document is legit. |
sexMatchesNationalIdentity | OCR | Verify gender on the customer’s profile matches the national identity document. |
serialNumberMatchesNationalIdentity | OCR | Verify the serial number on the customer’s profile matches their national identity document. |
issueDateMatchesNationalIdentity | OCR | Verify the ID issue date on the customer’s profile matches their national identity document. |
taxNumberMatchesNationalDatabase | OCR | Verify tax number on the customer’s profile matches the third-party database. |
taxPayerNameMatchesNationalDatabase | OCR | Verify tax payer’s name on the customer’s profile matches the third-party database. |
taxDocumentMatchesNationalDatabase | Compliance | |
minorCheck | Compliance | |
issueDateMatchesPassport | Compliance | |
worldCheck | Compliance | First name, last name, identity number, and date of birth checks with world check API |
selfieMatchesDriversLicence | OCR | Verify if the selfie uploaded to the customer’s profile matches the facial image on the driving license document. |
firstNameMatchesDriversLicence | OCR | Verify if the first name on the customer’s profile matches the first name on the driving license document. |
lastNameMatchesDriversLicence | OCR | Verify if the last name on the customer’s profile matches the last name on the driving license document. |
identityNumberMatchesDriversLicence | OCR | Verify if the national ID number on the customer’s profile matches the ID number on the driving license document. |
driversLicenseIsLegitimate | OCR | Verify if an uploaded driving licence document is legit. |
dateOfBirthMatchesDriversLicence | OCR | Verify if the date of birth on the customer’s profile matches the date of birth on their driver's license. |
temporaryIdentityIsLegitimate | OCR | Verify if an uploaded Temporary Identity document is legit. |
selfieMatchesTemporaryIdentity | OCR | Verify if the selfie uploaded to the customer’s profile matches the facial image on the temporary identity document. |
firstNameMatchesTemporaryIdentity | OCR | Verify if the first name on the customer’s profile matches the first name on the temporary identity document. |
lastNameMatchesTemporaryIdentity | OCR | Verify if the last name on the customer’s profile matches the last name on the temporary identity document. |
idNumberMatchesTemporaryIdentity | OCR | Verify the ID number on the customer’s profile matches the ID number on the temporary identity document. |
dateOfBirthMatchesTemporaryIdentity | OCR | Verify date of birth on the customer’s profile matches the temporary identity document. |
isTemporaryIdentityExpiryDateMatch | OCR | Verify temporary ID expiry date on the customer’s profile matches the temporary ID. |
permitIsLegitimate | OCR | Verify if an uploaded permit document is legit. |
lastNameMatchesPermit | OCR | Verify if the surname on the customer’s profile matches the surname on the permit. |
passportNumberMatchesPermit | OCR | Verify if the passport number on the customer’s profile matches the passport number on the permit. |
isPermitExpiryDateMatch | OCR | Verify the permit expiry date on the customer’s profile matches the permit expiry date on the permit. |
Asynchronous ratify items
Ratify items by default are executed synchronously when the ratify endpoint is called. However in certain circumstances you may want to run these tests in the background and not delay the completion of the KYC algorithm, especially if they are long running tests that do not prevent a wallet from being opened.
For example you may want to run a 3rd party compliance check that takes several minutes to complete - the test will not prevent a wallet being opened but it could raise a ticket for a compliance team to investigate if it failed. This is controlled by tenant config async.ratify.items, a comma-separated list of ratify items that need to be run asynchronously e.g.
async.ratify.items=secureCitizenCheck,pepCheck
KYC/B Rulesets
KYC rulesets combine the ratify items to create the rules that must be met to open a wallet. Eclipse has a simple but powerful expression language for configuring KYC/B rulesets that combines ratify items using boolean logic. In the background this expression language uses Javassist. Javassist is a flexible mechanism whereby complex business logic can be defined and compiled at a runtime – i.e. no deployment is required for changes.
KYC/B rulesets can be viewed in the Eclipse Admin Portal annotated over KYC results. The intention with this simple but powerful expression language is that the business rules that define KYC/B can be understood, configured, tested and supported by the business subject matter experts without the need for development resources.
Note
KYC/B rulesets are typically implemented using the simple but powerful expression language shown above. These rulesets can also be implemented directly in Javassist if there are edge case scenarios not supported in the expression ruleset language. In most cases expression rulesets should be used.
The system can determine what type of wallets a customer is eligible for depending on the level of completed KYC/B checks by calling the wallet-types endpoint for the customer or for the organisation.
Rulesets are dependent on region and sponsor bank. In South Africa assuming R3k daily and R25k monthly limit on a wallet we would use the Nedbank ruleset:
Ruleset Name | Rules |
---|---|
Nedbank | SelfieIsASelfie AND SelfieMatchesNationalIdentity AND LastNameMatchesNationalIdentity AND IdentityNumberMatchesNationalIdentity OR SelfieIsASelfie AND SelfieMatchesPassport AND FirstNameMatchesPassport AND LastNameMatchesPassport AND PassportNumberMatchesPassport OR SelfieIsASelfie AND selfieMatchesAsylumPaper AND firstNameMatchesAsylumPaper AND lastNameMatchesAsylumPaper AND AsylumPaperRefNumberMatchesAsylumPaper |
Nedbank Complete | SelfieIsLegitimate AND SelfieIsASelfie AND SelfieMatchesNationalIdentity AND LastNameMatchesNationalIdentity AND IdentityNumberMatchesNationalIdentity AND DateOfBirthMatchesNationalIdentity OR SelfieIsLegitimate AND SelfieIsASelfie AND SelfieMatchesPassport AND FirstNameMatchesPassport AND LastNameMatchesPassport AND PassportNumberMatchesPassport AND DateOfBirthMatchesPassport OR SelfieIsLegitimate AND SelfieIsASelfie AND selfieMatchesAsylumPaper AND firstNameMatchesAsylumPaper AND lastNameMatchesAsylumPaper AND AsylumPaperRefNumberMatchesAsylumPaper AND DateOfBirthMatchesAsylumPaper |
Nedbank Complete Expiry Date | SelfieIsLegitimate AND SelfieIsASelfie AND SelfieMatchesNationalIdentity AND LastNameMatchesNationalIdentity AND IdentityNumberMatchesNationalIdentity AND DateOfBirthMatchesNationalIdentity OR SelfieIsLegitimate AND SelfieIsASelfie AND SelfieMatchesPassport AND FirstNameMatchesPassport AND LastNameMatchesPassport AND PassportNumberMatchesPassport AND IsPassportExpiryDateMatch AND DateOfBirthMatchesPassport OR SelfieIsLegitimate AND SelfieIsASelfie AND selfieMatchesAsylumPaper AND firstNameMatchesAsylumPaper AND lastNameMatchesAsylumPaper AND AsylumPaperRefNumberMatchesAsylumPaper AND IsAsylumPaperExpiryDateMatch AND DateOfBirthMatchesAsylumPaper |
KYC/B Rulesets for Wallet Types
Wallet types are linked to KYC/B rulesets in that the ruleset determines the ratify items that must pass for the particular wallet to be provided.
A wallet attribute “Kyc” (or “Kyb” for organization wallets) should be defined for all wallet types that are subject to KYC/B. This attribute will determine the KYC/B ruleset that applies to this wallet.
For South African customers, the Kyc attribute is set to either “nedbank”, "nedbankcomplete" or "nedbankcomplete.expirydate"
The system can determine what type of wallets a customer is eligible for depending on the level of completed KYC/B checks by calling the wallet-types endpoint for the customer or for the organisation.
Refer to the screenshot below showing allowed wallet types for a KYCed and non-KYCed customer profile.
The full set of ratify items - which were checked, which failed and passed and custom AVPs for certain ratify items - are returned in the response when initiating the KYC algorithm by calling the ratify endpoint. The tenant should process this response to determine what KYC rulesets have been passed and which wallet types can be provisioned. Below is an example snippet from a response:
{
"selfieIsLegitimate": {
"checked": true,
"passed": true,
"pending": false,
"score": 0.0,
"avps": [
{
"att": "FACIAL_PHOTO_DOCID",
"val": "1021587"
}
]
},
"selfieMatchesNationalIdentity": {
"checked": false,
"passed": false,
"pending": false,
"score": 0.0,
"avps": []
},
"firstNameMatchesNationalIdentity": {
"checked": false,
"passed": false,
"pending": false,
"score": 0.0,
"avps": []
},
"lastNameMatchesNationalIdentity": {
"checked": false,
"passed": false,
"pending": false,
"score": 0.0,
"avps": []
},
"identityNumberMatchesNationalIdentity": {
"checked": false,
"passed": false,
"pending": false,
"score": 0.0,
"avps": []
},
"selfieMatchesPassport": {
"checked": true,
"passed": true,
"pending": false,
"score": 99.75271606445313,
"avps": [
{
"att": "FACIAL_PHOTO_DOCID",
"val": "1021587"
},
{
"att": "PASSPORT_DOCID",
"val": "1011763"
}
]
},
"firstNameMatchesPassport": {
"checked": true,
"passed": true,
"pending": false,
"score": 0.0,
"avps": [
{
"att": "PASSPORT_DOCID",
"val": "1011763"
}
]
},
"lastNameMatchesPassport": {
"checked": true,
"passed": true,
"pending": false,
"score": 0.0,
"avps": [
{
"att": "PASSPORT_DOCID",
"val": "1011763"
}
]
},
"passportNumberMatchesPassport": {
"checked": true,
"passed": true,
"pending": false,
"score": 0.0,
"avps": [
{
"att": "PASSPORT_DOCID",
"val": "1011763"
}
]
},
"addressMatchesProofOfAddress": {
"checked": false,
"passed": false,
"pending": false,
"score": 0.0,
"avps": []
},
"pepCheck": {
"checked": true,
"passed": true,
"pending": false,
"score": 0.0,
"avps": []
},
"selfieMatchesNationalDatabase": {
"checked": true,
"passed": true,
"pending": false,
"score": 99.95262908935547,
"avps": [
{
"att": "firstName",
"val": "JOHN"
},
{
"att": "lastName",
"val": "DOE"
},
{
"att": "smartCardIssued",
"val": "false"
},
{
"att": "idIssueDate",
"val": "20090103"
},
{
"att": "idSequenceNo",
"val": "2"
},
{
"att": "deadIndicator",
"val": "false"
},
{
"att": "idBlocked",
"val": "false"
},
{
"att": "maritalStatus",
"val": ""
},
{
"att": "onHANIS",
"val": "true"
},
{
"att": "onNPR",
"val": "true"
},
{
"att": "birthPlaceCountryCode",
"val": "ZA"
},
{
"att": "facialImageAvailable",
"val": "true"
},
{
"att": "saFPSListedFraudster",
"val": "false"
},
{
"att": "saFPSListedVictim",
"val": "false"
},
{
"att": "saFPSProtectiveRegistration",
"val": "false"
}
]
},
"matchCheck": {
"checked": true,
"passed": true,
"pending": false,
"score": 0.0,
"avps": [
{
"att": "identityNumber",
"val": "1234567890"
},
{
"att": "firstName",
"val": "John"
},
{
"att": "lastName",
"val": "Doe"
},
{
"att": "smartCardIssued",
"val": "false"
},
{
"att": "dead",
"val": "false"
},
{
"att": "idBlocked",
"val": "false"
},
{
"att": "maritalStatus",
"val": ""
},
{
"att": "onHanis",
"val": "false"
},
{
"att": "phone1",
"val": "1234567890"
},
{
"att": "isFaceIdentical",
"val": "false"
},
{
"att": "faceScore",
"val": "0.0"
}
]
},
"passportIsLegitimate": {
"checked": true,
"passed": true,
"pending": false,
"score": 0.0,
"avps": [
{
"att": "passportMRZLines",
"val": "PAZAFDOE<<JOHN<94"
},
{
"att": "PASSPORT_DOCID",
"val": "1024763"
}
]
},
...........................
Required Configuration Items
These must be defined for a tenant, the following are the typical default ratify configurations:
Ratify Config Name | Comment |
---|---|
user.new.ratify.method | This should be set to true for all new tenants |
skip.ratify.deprecated.results | This should be set to true for all new tenants |
ratifyUserProcessors | This determines the KYC ratify items to be run. This is dependent on the region and sponsor bank so typically preconfigured. |
ratifyOrganisationProcessors | This determines the KYB ratify items to be run. This is dependent on the region and sponsor bank so typically preconfigured. |
Updated about 1 month ago