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:

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:

  1. Create customer and gatherer profile information.
  2. Gather customer documentation - optionally perform OCR and validate during upload.
  3. 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.
  4. 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.
  5. Perform AML checks e.g. internal deny list, UN/OFAC/UK sanctions list, PEP, MATCH.
  6. 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:

  1. Passport number
  2. Expiry date
  3. Birth date
  4. First name
  5. Last Name
  6. Sex
  7. 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:

  1. Eclipse Hosted AWS Liveness - in this scenario tenants only need to serve a web view hosted by Eclipse to complete the liveness detection
  2. 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.

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:

  1. Position their face within the oval shape
  2. Click the Start Video check button to begin
  3. Folllow on screen instructions to complete the process

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 ItemType (OCR/ Compliance)Description
selfieIsLegitimateOCRLiveness check on the provided selfie.
selfieMatchesNationalIdentityOCRVerify if the selfie uploaded to the customer’s profile matches the facial image on the national identity document.
firstNameMatchesNationalIdentityOCRVerify if the first name on the customer’s profile matches the first name on the national identity document.
lastNameMatchesNationalIdentity checkOCRVerify if the last name on the customer’s profile matches the last name on the national identity document.
identityNumberMatchesNationalIdentityOCRVerify if the national ID number on the customer’s profile matches the ID number on the national identity document.
selfieMatchesPassportOCRVerify if the selfie uploaded to the customer’s profile matches the facial image on their passport.
firstNameMatchesPassportOCRVerify if the first name on the customer’s profile matches the first name on their passport.
lastNameMatchesPassportOCRVerify if the last name on the customer’s profile matches the last name on their passport
passportNumberMatchesPassportOCRVerify if the passport number on the customer’s profile matches the passport number on their passport.
addressMatchesProofOfAddressOCRVerify if the address details on the client’s profile match the uploaded proof of address document.
pepCheckComplianceCheck whether User are on the Politically exposed persons List
NOTE: Only available in South Africa
selfieMatchesNationalDatabaseComplianceCheck whether the Selfie taken matches the National Database photo
matchCheckComplianceMastercard 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
passportIsLegitimateOCRVerify if an uploaded passport document is legit.
isPassportExpiryDateMatchOCRVerify the passport expiry date added to the customer profile with the expiry date on their passport.
nationalIdentityIsLegitimateOCRVerify if an uploaded identification document is legit.
firstNameMatchesAsylumPaperOCRVerify if the first name on the customer’s profile matches the first name on the asylum paper.
lastNameMatchesAsylumPaperOCRVerify if the last name on the customer’s profile matches the last name on the asylum paper.
dateOfBirthMatchesAsylumPaperOCRVerify if the date of birth on the customer’s profile matches the date of birth on the asylum paper.
selfieMatchesAsylumPaperOCRVerify if the selfie uploaded to the customer’s profile matches the facial image on their asylum paper.
asylumPaperRefNumberMatchesAsylumPaperOCRVerify if the asylum reference number on the customer’s profile matches the reference number on the asylum document.
asylumPaperIsLegitimateOCRVerify if the asylum paper is legit.
firstNameMatchesBirthCertificateOCRVerify if the first name on the customer’s profile matches the first name on their birth certificate.
lastNameMatchesBirthCertificateOCRVerify if the last name on the customer’s profile matches the last name on their birth certificate.
isDateOfBirthMatchesBirthCertificateOCRVerify if the date of birth on the customer’s profile matches the date of birth on their birth certificate.
taxNumberMatchesTaxDocumentOCRVerify the Tax number added to the customer profile with the uploaded ‘TaxDocument’
firstNameMatchesTaxDocumentOCRVerify the First name added to the customer’s profile with the uploaded “TaxDocument”
lastNameMatchesTaxDocumentOCRVerify the Last name added to the customer’s profile with the uploaded “TaxDocument”
iprsCheckComplianceVerify the national ID added to the customer’s profile against the Kenyan Integrated Population Registration System (IPRS).
customListKycCheckComplianceDEPRICATED
internalBlackListCheckComplianceAllows Organisations to keep their own Black List of Customers
ukCheckComplianceCheck UK Sanctions List
ofacCheckComplianceCheck 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.
unCheckComplianceCheck UN Sanctions List
secureCitizenCheckComplianceCitizen & Credit Check
NOTE: Only available in South Africa
bankStatementIsLegitimateOCRVerify if the bank statement is legit.
nameMatchesVerifiedBankStatementOCR
firstNameMatchesForeignCertificateOCRVerify the First name added to the customer profile with the uploaded ‘ForeignCertificate’
lastNameMatchForeignCertificateOCRVerify the Last name added to the customer profile with the uploaded ‘ForeignCertificate’
dateOfBirthMatcheForeignCertificateOCRVerify date of Birth added in customer profile with uploaded ‘ForeignCertificate’
usaWNineIsLegitimateOCRThe letters “W-9” must be found on the uploaded document type 'usaw9'
backOfNationalIdentityIsLegitimateOCRVerify if the back of the national identity document is legit.
serialNumberMatchesBackOfNationalIdentityOCRVerify the serial number on the customer’s profile matches the back of their national identity document.
idNumberMatchesBackOfNationalIdentityOCRVerify the ID number on the customer’s profile matches the back of their national identity document.
nameMatchesBackOfNationalIdentityOCRVerify the name on the customer’s profile matches the back of their national identity document.
dateOfBirthMatchesBackOfNationalIdentityOCRVerify the date of birth on the customer’s profile matches the back of their national identity document.
sexMatchesBackOfNationalIdentityOCRVerify the gender on the customer’s profile matches the back of their national identity document.
issueDateMatchesBackOfNationalIdentityOCRVerify the national ID issue date on the customer’s profile matches the back of their national identity document.
dateOfBirthMatchesPassportOCRVerify date of birth on the customer’s profile matches the passport.
dateOfBirthMatchesNationalIdentityOCRVerify date of birth on the customer’s profile matches the national identity document.
isAsylumPaperExpiryDateMatchOCRVerify asylum expiry date on the customer’s profile matches the asylum paper.
taxDocumentIsLegitimateOCRVerify the uploaded tax document is legit.
sexMatchesNationalIdentityOCRVerify gender on the customer’s profile matches the national identity document.
serialNumberMatchesNationalIdentityOCRVerify the serial number on the customer’s profile matches their national identity document.
issueDateMatchesNationalIdentityOCRVerify the ID issue date on the customer’s profile matches their national identity document.
taxNumberMatchesNationalDatabaseOCRVerify tax number on the customer’s profile matches the third-party database.
taxPayerNameMatchesNationalDatabaseOCRVerify tax payer’s name on the customer’s profile matches the third-party database.
taxDocumentMatchesNationalDatabaseCompliance
minorCheckCompliance
issueDateMatchesPassportCompliance
worldCheckComplianceFirst name, last name, identity number, and date of birth checks with world check API
selfieMatchesDriversLicenceOCRVerify if the selfie uploaded to the customer’s profile matches the facial image on the driving license document.
firstNameMatchesDriversLicenceOCRVerify if the first name on the customer’s profile matches the first name on the driving license document.
lastNameMatchesDriversLicenceOCRVerify if the last name on the customer’s profile matches the last name on the driving license document.
identityNumberMatchesDriversLicenceOCRVerify if the national ID number on the customer’s profile matches the ID number on the driving license document.
driversLicenseIsLegitimateOCRVerify if an uploaded driving licence document is legit.
dateOfBirthMatchesDriversLicenceOCRVerify if the date of birth on the customer’s profile matches the date of birth on their driver's license.

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 NameRules
NedbankSelfieIsASelfie 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 CompleteSelfieIsLegitimate 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 DateSelfieIsLegitimate 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.

KYC Attribute for a wallet type

KYC Attribute for a wallet type

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.

Allowed wallet types: KYCed customer profile

Allowed wallet types: KYCed customer profile

Allowed wallet types: Non-KYCed customer profile

Allowed wallet types: 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 NameComment
user.new.ratify.methodThis should be set to true for all new tenants
skip.ratify.deprecated.resultsThis should be set to true for all new tenants
ratifyUserProcessorsThis determines the KYC ratify items to be run. This is dependent on the region and sponsor bank so typically preconfigured.
ratifyOrganisationProcessorsThis determines the KYB ratify items to be run. This is dependent on the region and sponsor bank so typically preconfigured.