Customer Onboarding & KYC

Customer onboarding in Nucleus is governed by Central Bank of Nigeria (CBN) Anti-Money Laundering (AML/CFT) and Customer Due Diligence regulations. Nucleus provides a unified Customer Information File (CIF) architecture: whether an account is opened for an individual person or a multinational corporate entity, the engine derives a single, immutable CIF that binds all associated savings, fixed deposits, credit lines, and signatories.

Key Rules & Architectural Invariants

Branch Scoping Rule: All customers (Individual and Corporate) must be onboarded at an operating branch (officeId >= 2), not the Head Office. Head Office is reserved for corporate governance, audit, compliance, and treasury policy.

1. Personal Accounts (`legalFormId: 1`)

Personal customers require individual identity data, BVN validation, and KYC Tier classification.

Onboarding Request:

POST /nucleus/api/v1/clients?tenantIdentifier=pilot-mfb
Content-Type: application/json

{
  "officeId": 2,
  "firstname": "Amina",
  "lastname": "Danladi",
  "externalId": "CUST-00912",
  "staffId": 14,
  "dateFormat": "dd MMMM yyyy",
  "locale": "en",
  "active": true,
  "activationDate": "12 September 2026",
  "legalFormId": 1
}

Response:

{
  "officeId": 2,
  "clientId": 2,
  "resourceId": 2,
  "changes": {
    "cif": "CIF00000002",
    "accountNo": "000000002"
  }
}

2. Corporate Accounts (`legalFormId: 2`)

Corporate entities (Limited Liability Companies, Public Limited Companies, Partnerships, Sole Proprietorships, NGOs, Cooperatives) follow the exact same unified CIF process, while also capturing corporate registry data:

Corporate Entity Parameters:

legalFormId: Set to 2 (Entity / Non-Person).
fullname: The registered legal business name (e.g. Dangote Flour Mills Ltd).
clientNonPersonDetails:
- incorpNumber: Corporate Affairs Commission (CAC) Registration number (e.g. RC-1294812).
- constitutionId: Legal entity type (Code 200200 to 200207).
- mainBusinessLineId: Industry classification sector (Code 200220 to 200232).
- incorpValidityTillDate: Certificate validity / re-registration deadline.
- remarks: Line of business summary or KYC notes.
- scumlNumber: Special Control Unit Against Money Laundering registration (mandatory for DNFBPs).

Supported Legal Constitutions:

Constitution Code	Legal Entity Type
`200200`	Sole Proprietorship (Business Name)
`200201`	Partnership
`200202`	Private Limited Company (Ltd)
`200203`	Public Limited Company (PLC)
`200204`	Company Limited by Guarantee
`200205`	Incorporated Trustees (NGO / Association / Church)
`200206`	Cooperative Society
`200207`	Government Agency / Parastatal

Corporate Onboarding Request:

POST /nucleus/api/v1/clients?tenantIdentifier=pilot-mfb
Content-Type: application/json

{
  "officeId": 2,
  "fullname": "Dangote Flour Mills Ltd",
  "externalId": "CORP-001",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en",
  "active": true,
  "activationDate": "12 September 2026",
  "legalFormId": 2,
  "clientNonPersonDetails": {
    "constitutionId": 200202,
    "mainBusinessLineId": 200221,
    "incorpNumber": "RC-1294812",
    "incorpValidityTillDate": "12 September 2035",
    "remarks": "Food and Consumer Goods Manufacturing",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }
}

Corporate Response:

{
  "officeId": 2,
  "clientId": 3,
  "resourceId": 3,
  "changes": {
    "cif": "CIF00000003",
    "accountNo": "000000003"
  },
  "resourceExternalId": "CORP-001"
}

Notice that Dangote Flour Mills Ltd is issued CIF00000003 through the exact same automated CIF generator. All corporate accounts (operating current accounts, collection accounts, FX accounts, and credit facilities) bind to this single corporate CIF.

3. Corporate KYC Requirements & Compliance Checklist

Under Central Bank of Nigeria (CBN) AML/CFT Regulations and Customer Due Diligence guidelines, onboarding a corporate entity requires specific documentation and verified corporate officials before commercial accounts can be activated.

Mandatory Corporate Documents:

CAC Registration: Certificate of Incorporation and CAC Status Report (details of registered office, objects, directors, and share capital).
Constitutional Documents: Certified Memorandum & Articles of Association (MEMART) or Partnership Deed / Constitution.
Board Resolution: Duly signed resolution authorizing the opening of the account and designating authorized signatories.
Tax Identification Number (TIN): Mandatory corporate tax ID issued by the Federal Inland Revenue Service (FIRS) / JTB.
SCUML Certificate: Mandatory for Designated Non-Financial Businesses and Professions (DNFBPs)—such as real estate developers, car dealers, legal practitioners, audit firms, hotels, and casinos.
Ultimate Beneficial Ownership (UBO): Full disclosure of all natural persons who ultimately own or control $\ge 5\%$ of shares, voting rights, or executive authority.
Signatories & Directors Due Diligence: BVN, NIN, government-issued photo ID, and passport photograph for all authorized signatories and directors.
Two (2) Independent Bank References: Mandated by CBN for all current accounts (personal and corporate).
Physical Address Verification: Certified utility bill and physical visitation report.

4. Setting Corporate TIN & SCUML

Corporate KYC attributes (TIN and SCUML certificate details) are configured via the Corporate KYC endpoint:

PUT /nucleus/api/v1/clients/{clientId}/corporatekyc
Nucleus-Platform-TenantId: pilot-mfb
Content-Type: application/json

{
  "tin": "10982347-0001",
  "scumlNumber": "SC-1204918-LA",
  "scumlExpiry": "2029-09-12"
}

5. Adding Corporate Officials (Directors, Signatories, UBOs)

CBN guidelines mandate recording every person with management control, signing authority, or significant ownership:

POST /nucleus/api/v1/clients/{clientId}/officials
Nucleus-Platform-TenantId: pilot-mfb
Content-Type: application/json

{
  "officialType": "BENEFICIAL_OWNER",
  "name": "Aliko Dangote",
  "bvn": "22212345678",
  "tin": "10023456",
  "ownershipPct": 75.0,
  "phone": "+2348030000001",
  "email": "aliko@dangote.com"
}

Supported officialType values:

DIRECTOR: Statutory board member listed on CAC Status Report.
SIGNATORY: Authorized mandate holder (Class A / Class B).
BENEFICIAL_OWNER: Natural person holding $\ge 5\%$ equity or controlling interest.

6. Current Account 2-Referee Mandate Enforcement

CBN Current Account Rule: Any deposit account configured with overdraft capability or designated as a Current Account requires at least two (2) verified bank references on file. Attempting to activate an account with fewer than 2 references will return 403 Forbidden (error.msg.savingsaccount.current.references.required).

Adding Referees:

POST /nucleus/api/v1/savingsaccounts/{savingsAccountId}/references
Nucleus-Platform-TenantId: pilot-mfb
Content-Type: application/json

{
  "refereeName": "Zenith Bank Plc",
  "refereeAccountNo": "1012345678",
  "refereeBank": "057",
  "refereePhone": "+23412787000",
  "refereeEmail": "references@zenithbank.com",
  "refereeAddress": "Plot 84, Ajose Adeogun, VI, Lagos",
  "relationship": "Commercial Banker for 10 years"
}

Once two references are registered, the account can be activated via:

POST /nucleus/api/v1/savingsaccounts/{savingsAccountId}?command=activate

7. CBN KYC Tiers

Nucleus natively enforces transaction and balance limits across the 3 CBN KYC tiers:

Tier	Maximum Single Deposit	Maximum Cumulative Balance	Requirements
Tier 1 (Low Value)	₦50,000	₦300,000	Basic personal info, passport photograph, phone number
Tier 2 (Medium Value)	₦100,000	₦500,000	Verified BVN, national identity card (NIN), proof of address
Tier 3 (High Value / Corporate)	Unlimited	Unlimited	Corporate entity status, full CAC documents, TIN, UBO, 2 referees

Corporate entities (legalFormId: 2) are automatically classified as Tier 3 upon onboarding, allowing unlimited corporate transaction volumes.

8. The Relationship Officer’s CABAL Book

In Nigerian banking operations, the CABAL refers to an Account Officer’s or Relationship Manager’s assigned customer book:

Account Officer (Role 320013): Scoped strictly to their own assigned portfolio (staffId). They can view, track deposit mobilization, and manage loan appraisals for customers in their CABAL.
Head Office & Branch Managers: Can inspect the consolidated customer base or view the CABAL broken down by branch, account type, and relationship officer.

Overview

Digital Banking & Mobile APIs

Core Banking Workflows

Infrastructure & Operations

Key Rules & Architectural Invariants

1. Personal Accounts (`legalFormId: 1`)

Onboarding Request:

Response:

2. Corporate Accounts (`legalFormId: 2`)

Corporate Entity Parameters:

Supported Legal Constitutions:

Corporate Onboarding Request:

Corporate Response:

3. Corporate KYC Requirements & Compliance Checklist

Mandatory Corporate Documents:

4. Setting Corporate TIN & SCUML

5. Adding Corporate Officials (Directors, Signatories, UBOs)

6. Current Account 2-Referee Mandate Enforcement

Adding Referees:

7. CBN KYC Tiers

8. The Relationship Officer’s CABAL Book

​Key Rules & Architectural Invariants

​1. Personal Accounts (legalFormId: 1)

​Onboarding Request:

​Response:

​2. Corporate Accounts (legalFormId: 2)

​Corporate Entity Parameters:

​Supported Legal Constitutions:

​Corporate Onboarding Request:

​Corporate Response:

​3. Corporate KYC Requirements & Compliance Checklist

​Mandatory Corporate Documents:

​4. Setting Corporate TIN & SCUML

​5. Adding Corporate Officials (Directors, Signatories, UBOs)

​6. Current Account 2-Referee Mandate Enforcement

​Adding Referees:

​7. CBN KYC Tiers

​8. The Relationship Officer’s CABAL Book

Key Rules & Architectural Invariants

1. Personal Accounts (`legalFormId: 1`)

Onboarding Request:

Response:

2. Corporate Accounts (`legalFormId: 2`)

Corporate Entity Parameters:

Supported Legal Constitutions:

Corporate Onboarding Request:

Corporate Response:

3. Corporate KYC Requirements & Compliance Checklist

Mandatory Corporate Documents:

4. Setting Corporate TIN & SCUML

5. Adding Corporate Officials (Directors, Signatories, UBOs)

6. Current Account 2-Referee Mandate Enforcement

Adding Referees:

7. CBN KYC Tiers

8. The Relationship Officer’s CABAL Book