Skip to main content
The KYB (Know Your Business) module verifies corporate entities before they transact. It integrates with the Corporate Affairs Commission (CAC) to validate company registration, verify directors through KYC identity checks, and screen beneficial owners against global sanctions lists.

​
When KYB Screening Triggers

KYB checks run automatically during transaction screening when the transaction metadata indicates a business entity: 
{
  "metadata": {
    "entityType": "BUSINESS",
    "senderRcNumber": "RC123456"
  }
}
Either entityType: "BUSINESS" or the presence of senderRcNumber will trigger the KYB Verification layer in the screening pipeline.

​
KYB Application Workflow

Create Application
       │
       ▼
CAC Lookup ──► Director Verification ──► BO Screening ──► Compliance Review
(RC Number)      (KYC per director)       (Sanctions)       (Approve/Reject)
StepActionWho
1Submit KYB application with company name, RC number, TINCompliance Officer
2Run CAC lookup -fetch company details, directors, beneficial ownersCOMPLIANCE_OFFICER
3Verify each director’s identity via NIN/BVNCOMPLIANCE_OFFICER
4Screen beneficial owners against sanctionsCOMPLIANCE_OFFICER
5Approve or reject the applicationBANK_ADMIN, COMPLIANCE_OFFICER

​
KYB Statuses

StatusMeaning
PENDINGApplication submitted, awaiting CAC lookup
CAC_VERIFIEDCAC lookup successful, company details confirmed
DIRECTORS_VERIFIEDAll directors passed identity verification
BENEFICIAL_OWNERS_VERIFIEDBeneficial owners screened, no sanctions hits
DOCUMENT_UPLOADEDSupporting documents uploaded
SCREENING_PASSEDAll compliance checks passed
APPROVEDFully verified — business can transact freely
REJECTEDFailed verification or sanctions hit found

​
Approval Workflow

KYB applications can be approved from DIRECTORS_VERIFIED, BENEFICIAL_OWNERS_VERIFIED, or DOCUMENT_UPLOADED status. The compliance officer reviews CAC results, director verifications, and beneficial owner screenings before approving.

​
Screening Impact for Business Transactions

When a business transaction is screened, the KYB Verification engine evaluates the sender’s KYB status:
ConditionScoreOutcomeWhat Happens
No KYB record100BLOCKTransaction blocked, officer notified, business prompted to complete KYB
PENDING / CAC_VERIFIED / DIRECTORS_VERIFIED / BENEFICIAL_OWNERS_VERIFIED / DOCUMENT_UPLOADED / SCREENING_PASSED100BLOCKVerification incomplete — transaction blocked
APPROVED0APPROVEFully verified — no risk contribution
REJECTED100BLOCKTransaction blocked, case created automatically
Note: KYB screening is inserted into the pipeline immediately after KYC Verification. For individual transactions (entityType: "INDIVIDUAL" or absent), the KYB engine contributes zero score.

​
CAC Provider

The CACProvider performs company lookups by RC number. It operates in two modes:
ModeBehavior
LiveCalls the real CAC API when CAC_API_KEY is configured
MockReturns synthetic company data for demos when no API key is set
Mock mode is useful for demonstrations and development. For production, configure CAC_API_KEY in your environment.

​
Document Upload & Storage

KYB applications support document uploads via the API. Documents are stored in MinIO (S3-compatible object storage) and referenced in the database.

​
Supported Document Types

TypeDescription
CAC_CERTIFICATECAC registration certificate
MEMARTMemorandum and Articles of Association
TAX_CLEARANCETax clearance certificate
BOARD_RESOLUTIONBoard resolution document
AUDITED_ACCOUNTSAudited financial accounts
UTILITY_BILLUtility bill (address proof)
DIRECTOR_IDDirector’s identity document
BENEFICIAL_OWNER_IDBeneficial owner’s identity document
OTHERAny other document

​
Document Endpoints

MethodEndpointDescription
POST/api/v1/kyc/kyb/applications/:id/documentsUpload document (multipart/form-data)
GET/api/v1/kyc/kyb/applications/:id/documentsList documents with presigned URLs
GET/api/v1/kyc/kyb/applications/:id/documents/:docId/downloadGet 5-minute presigned download URL
DELETE/api/v1/kyc/kyb/applications/:id/documents/:docIdDelete document (admin only)

​
Upload Example

curl -X POST /api/v1/kyc/kyb/applications/kyb_abc123/documents \
  -H "Authorization: Bearer <token>" \
  -F "file=@cac_certificate.pdf" \
  -F "documentType=CAC_CERTIFICATE"
Note: Documents are tenant-scoped and stored under kyb/{applicationId}/ in MinIO.

​
Permissions

ActionWho Can Do It
Create KYB applicationBANK_ADMIN, COMPLIANCE_OFFICER
Run CAC lookupBANK_ADMIN, COMPLIANCE_OFFICER
Verify directorsBANK_ADMIN, COMPLIANCE_OFFICER
Screen beneficial ownersBANK_ADMIN, COMPLIANCE_OFFICER
Approve/reject KYBBANK_ADMIN, COMPLIANCE_OFFICER