> ## 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.

# KYB Verification

> Know Your Business -corporate verification via CAC lookup, director identity checks, and beneficial owner sanctions screening

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:

```json theme={null}
{
  "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)
```

| 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 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       |
| `BENEFICIAL_OWNERS_VERIFIED` | Beneficial owners screened, no sanctions hits    |
| `DOCUMENT_UPLOADED`          | Supporting documents uploaded                    |
| `SCREENING_PASSED`           | All compliance checks passed                     |
| `APPROVED`                   | Fully verified — business can transact freely    |
| `REJECTED`                   | Failed 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:

| Condition                                                                                                                 | Score | Outcome   | What Happens                                                             |
| ------------------------------------------------------------------------------------------------------------------------- | ----- | --------- | ------------------------------------------------------------------------ |
| **No KYB record**                                                                                                         | 100   | `BLOCK`   | Transaction blocked, officer notified, business prompted to complete KYB |
| **PENDING / CAC\_VERIFIED / DIRECTORS\_VERIFIED / BENEFICIAL\_OWNERS\_VERIFIED / DOCUMENT\_UPLOADED / SCREENING\_PASSED** | 100   | `BLOCK`   | Verification incomplete — transaction blocked                            |
| **APPROVED**                                                                                                              | 0     | `APPROVE` | Fully verified — no risk contribution                                    |
| **REJECTED**                                                                                                              | 100   | `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 |

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

| 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

```bash theme={null}
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` |