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:

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

1. The AWS session ID expires 3 minutes after it has been issued.
2. 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:

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

📘

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:

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:

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"
			}
		]
	},
...........................

Document Validations

The following validations is performed on the Documents provided as part of KYC validation:

Mandatory Information

The following information must be supplied as part of onboarding:

KYC

KYB

Required Configuration Items

These must be defined for a tenant, the following are the typical default ratify configurations:

For African Bank KYC/KYB, the following Tenant configurations are required in order to enable Risk Calculation:

For African Bank KYC/KYB, the following Global configurations are required in order to enable Risk Calculation:

KYC Process for Minors

To successfully onboard a minor, both the minor and the adult need to have their own customer profiles created on Eclipse, and KYC has to be run and passed on both customer profiles (the minor and the adult) for a wallet to create successfully for the minor. As part of this process, a family organisation is created to facilitate the relationship between the adult and the minor, and POPI consent is received and attached to the adult's customer profile.

The below process describes the steps that need to be followed to successfully open a wallet for a minor, as well as the prerequisites of each step. In summary, they are:

1. Customer Creation of the Adult and Minor
2. Document Upload to the Adult and Minor
3. Creation of the Family Organisation
4. Linking of the Adult and Minor User Positions to the Family Organisation
5. POPI Attachment
6. Running KYC on the Adult and Minor
7. Creation of the Wallet

Note that some of the steps above are interchangeable.

Customer Creation of the Adult and the Minor

Create the customer. Ensure that all mandatory fields have been passed as part of customer creation to avoid having updating the customer after KYC (see mandatory fields above). There are no prerequisites to this step. A customer will need to be created for the adult, and a customer will need to be created for the minor. Customer creation can be done by calling the following:

Post https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/customers

Sample Request for Customer Creation:

{  
  "title": "MR",  
  "firstName": "TestName",  
  "middleName": "TestMidName",  
  "lastName": "TestSurname",  
  "gender": "M",  
  "email": "[email protected]",  
  "maritalStatus": "S",  
  "dateOfBirth": "20000101",  
  "birthCity": "Johannesburg",  
  "birthCountry": "ZA",  
  "phone1": "0112345678",  
  "nationalIdentityNumber": "0001010011081",  
  "externalUniqueId": "b61c94a2-0378-4512-a134-e30b45fc0609",  
  "sourceOfFunds": "Salary",  
  "profession": "Administrator",  
  "nationality": "South Africa",  
  "countryOfResidence": "South Africa",  
  "industry": "Ecommerce",  
  "monthlyIncome": 10000,  
  "purposeOfUse": "Savings"  
}

Sample Response for Successful Customer Creation:

{  
  "customerId": 8580673,  
  "title": "MR",  
  "gender": "T",  
  "firstName": "TestName",  
  "middleName": "TestMidName",  
  "lastName": "TestSurname",  
  "phone1": "0112345678",  
  "email": "[email protected]",  
  "nationalIdentityNumber": "0001010011081",  
  "version": 0,  
  "created": "2024-11-19T09:13:15.000Z",  
  "lastModified": "2024-11-19T09:13:15.000Z",  
  "dateOfBirth": "20000101",  
  "birthCity": "Johannesburg",  
  "birthCountry": "ZA",  
  "maritalStatus": "S",  
  "externalUniqueId": "b61c94a2-0378-4512-a134-e30b45fc0609",  
  "status": "ACTIVE",  
  "nationality": "South Africa",  
  "positions": \[],  
  "sourceOfFunds": "Salary",  
  "industry": "Ecommerce",  
  "monthlyIncome": 10000,  
  "purposeOfUse": "Savings",  
  "countryOfResidence": "South Africa",  
  "profession": "Administrator"  
}

The customerId that is returned in the response will be an important reference for the subsequent steps.

Document Upload to the Adult and Minor

Upload the documents necessary for the customer. This includes documents such as national identity, permit, passport, etc. Note that the documents need to be uploaded to the relevant customer profile, i.e. documents relating to the adult must be uploaded to the adult's customer profile, and documents relating to the minor must be uploaded to the minor's customer profile. The prerequisite of this step is a customerId.

Post https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/documents

Sample Request to Attach a Birth Certificate:

{  
  "base64EncodedDocument": "/9j/4AAQSkZJRgABAQEAYA...",  
  "documentType": "BIRTH_CERTIFICATE",  
  "mediaType": "image/jpeg"  
}

Sample Response for Document Creation:

{  
  "documentId":2222987,  
  "documentType":"BIRTH_CERTIFICATE",  
  "customerId":8580673,  
  "mediaType":"image/jpeg",  
  "created":"2024-11-19T09:21:17.000Z",  
  "lastModified":"2024-11-19T09:21:17.000Z",  
  "version":0,  
  "extraInfo":"{ocrResult:...}",  
  "isHistoricalDocument":false  
  }

Creation of the Family Organisation

The organisation is created to establish the relationship between the minor and the parent/legal guardian. The family organisation can have multiple MEMBER user positions associated to a single HEAD. The name of the organisation should be "Family Organisation x" where x represents the customerId of the adult.

Post https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/organisations

Sample Request for the Creation of a Family Organisation:

{  
  "organisationId": null,  
  "companyNumber": null,  
  "created": null,  
  "email": null,  
  "externalUniqueId": "d66841fc-8cf1-4f65-9ac8-aa6216fdf059",  
  "industrialClassification": null,  
  "industrialSector": null,  
  "lastModified": null,  
  "name": "Family Organisation 123456",  
  "phone1": "0112345678",  
  "phone2": null,  
  "taxNumber": null,  
  "tradingName": null,  
  "version": null,  
  "bankName": null,  
  "accountNumber": null,  
  "bankDetails": \[],  
  "categoryCode": null,  
  "vatNumber": null,
  "type": "FAMILY",
  "merchantId": null  
}

Sample Response for the Successful Creation of a Family Organisation:

{  
  "organisationId": 999140,  
  "name": "Family Organisation 123456",  
  "phone1": "0112345678",  
  "created": "2024-11-19T09:28:00.000Z",  
  "lastModified": "2024-11-19T09:28:00.000Z",  
  "version": 0,  
  "externalUniqueId": "d66841fc-8cf1-4f65-9ac8-aa6216fdf059",  
  "bankDetails": \[]  
}

Linking of the Adult and Minor User Positions to the Family Organisation

The user position for the parent is "HEAD" and the user position of the minor is "MEMBER". Both are associated to the family organisation, to successfully establish the relationship between the two. The prerequisites of this step are customer profiles (in the name of the adult and of the minor,) and a family organisation. Both the customerId and organisationId are used.

Post https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/positions

Sample Request for Linking Customer to the Family Organisation:

{  
  "position": "HEAD",  
  "customerId": 8579670  
}

Sample Response for Successful User Position Linking:

{  
  "position": "HEAD",  
  "customerId": 8579670  
}

POPI Attachment

Attach POPI Consent to the Head of the family once received. Note: the naming convention of the attachment type is "POPIA_consent-x" where x is the customerId of the minor. The prerequisite of this step is an adult customer profile.

Post https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/attachments

The sample request to create an attachment on a customer is as follows:

{  
  "attachmentType": "POPIA_consent-8579671",  
  "base64EncodedAttachment": "Pw==",  
  "info": "yes",  
  "mediaType": "text/plain"  
}

Running KYC on the Adult and Minor

One the above steps have been completed, KYC is run on the adult and on the minor. Once KYC has passed on both customer profiles, the wallet can be created on the minor's profile.

Post https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify