Documentation Index
Fetch the complete documentation index at: https://docs.verifow.com/llms.txt
Use this file to discover all available pages before exploring further.
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"
}
}
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)
| Step | Action | Who |
|---|
| 1 | Submit KYB application with company name, RC number, TIN | Compliance Officer |
| 2 | Run CAC lookup -fetch company details, directors, beneficial owners | COMPLIANCE_OFFICER |
| 3 | Verify each director’s identity via NIN/BVN | COMPLIANCE_OFFICER |
| 4 | Screen beneficial owners against Watchman sanctions | COMPLIANCE_OFFICER |
| 5 | Approve or reject the application | BANK_ADMIN, COMPLIANCE_OFFICER |
KYB Statuses
| Status | Meaning |
|---|
PENDING | Application submitted, awaiting CAC lookup |
CAC_VERIFIED | CAC lookup successful, company details confirmed |
DIRECTORS_VERIFIED | All directors passed identity verification |
BOS_VERIFIED | Beneficial owners screened, no sanctions hits |
APPROVED | Fully verified -business can transact freely |
REJECTED | Failed verification or sanctions hit found |
Screening Impact for Business Transactions
When a business transaction is screened, the KYB Verification engine evaluates the sender’s KYB status:
| Condition | Score | Outcome | What Happens |
|---|
| No KYB record | 60 | REVIEW | Officer notified, business prompted to complete KYB |
| PENDING / CAC_VERIFIED / DIRECTORS_VERIFIED | 40 | REVIEW | Verification in progress -transaction flagged for review |
| BOS_VERIFIED | 10 | APPROVE | Partially verified -low risk contribution |
| APPROVED | 0 | APPROVE | Fully verified -no risk contribution |
| REJECTED | 85 | BLOCK | Transaction 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:
| Mode | Behavior |
|---|
| Live | Calls the real CAC API when CAC_API_KEY is configured |
| Mock | Returns synthetic company data for demos when no API key is set |
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
| Type | Description |
|---|
CAC_CERTIFICATE | CAC registration certificate |
MEMART | Memorandum and Articles of Association |
TAX_CLEARANCE | Tax clearance certificate |
BOARD_RESOLUTION | Board resolution document |
AUDITED_ACCOUNTS | Audited financial accounts |
UTILITY_BILL | Utility bill (address proof) |
DIRECTOR_ID | Director’s identity document |
BENEFICIAL_OWNER_ID | Beneficial owner’s identity document |
OTHER | Any other document |
Document Endpoints
| Method | Endpoint | Description |
|---|
POST | /api/v1/kyc/kyb/applications/:id/documents | Upload document (multipart/form-data) |
GET | /api/v1/kyc/kyb/applications/:id/documents | List documents with presigned URLs |
GET | /api/v1/kyc/kyb/applications/:id/documents/:docId/download | Get 5-minute presigned download URL |
DELETE | /api/v1/kyc/kyb/applications/:id/documents/:docId | Delete 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
| Action | Who Can Do It |
|---|
| Create KYB application | BANK_ADMIN, COMPLIANCE_OFFICER |
| Run CAC lookup | BANK_ADMIN, COMPLIANCE_OFFICER |
| Verify directors | BANK_ADMIN, COMPLIANCE_OFFICER |
| Screen beneficial owners | BANK_ADMIN, COMPLIANCE_OFFICER |
| Approve/reject KYB | BANK_ADMIN, COMPLIANCE_OFFICER |
