Skip to content

Instantly share code, notes, and snippets.

@adejorosam

adejorosam/gist:82c3eb476ba9ded349e4e17a093f3620

Last active January 22, 2026 10:51
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save adejorosam/82c3eb476ba9ded349e4e17a093f3620 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save adejorosam/82c3eb476ba9ded349e4e17a093f3620 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
gistfile1.md

NITECH (InterfaceX) Endpoint Integration - Documentation

Date: January 22, 2026 Version: 1.0

Overview

This document outlines the changes made to integrate new and updated NITECH (InterfaceX) endpoints into the Cardinalstone Registrars backend system.

Table of Contents

  1. New Endpoints Added
  2. Updated Endpoints
  3. Existing Endpoints (No Changes)
  4. API Reference
  5. Files Modified

New Endpoints Added

1. Verify Shareholder Warrants

NITECH Endpoint: Verifyshareholderwarrants

API Route: POST /api/registrars/verifyShareholderWarrants

Authentication: Required (Bearer Token)

Request Body:

{
  "accountNumber": 12345,
  "registerID": 100,
  "warrantType": "DW"
}
Parameter Type Required Description
accountNumber int Yes The holder's account number
registerID int Yes The register ID
warrantType string Yes Warrant type: DW (Dividend Warrant), IW (Interest Warrant), or RW (Rights Warrant)

Response: Status OK or ErrorMessage

2. Get Holder Types

NITECH Endpoint: GetHolderTypes

API Route: GET /api/registrars/getHolderTypes

Authentication: Not required

Request Parameters: None

Response:

[
  {
    "HolderTypeId": "string",
    "HolderTypeName": "string",
    "HolderTypeCategory": "string"
  }
]

3. Get Register Range

NITECH Endpoint: Getregisterrange

API Route: GET /api/registrars/getRegisterRange

Authentication: Not required

Request Parameters (Query):

Parameter Type Required Description
registerID int Yes The register ID
asatDate string Yes As-at date in yyyy-mm-dd format

Example: /api/registrars/getRegisterRange?registerID=100&asatDate=2024-09-18

Response:

[
  {
    "TotalCount": 500,
    "Units": 1000000.00,
    "BeginRange": 1,
    "EndRange": 1000,
    "RangeId": 1
  }
]

4. Get Holder Type Analysis

NITECH Endpoint: GetHolderTypeAnalysis

API Route: GET /api/registrars/getHolderTypeAnalysis

Authentication: Not required

Request Parameters (Query):

Parameter Type Required Description
registerID int Yes The register ID
asatDate string Yes As-at date in yyyy-mm-dd format

Example: /api/registrars/getHolderTypeAnalysis?registerID=100&asatDate=2024-09-18

Response:

[
  {
    "CompanyName": "string",
    "ShareHolderName": "string",
    "ShareHolderAddress": "string",
    "TotalUnits": 50000.00,
    "TotalUnitsDec": 50000.0000,
    "PercentUnits": 5.25,
    "PercentUnitsDec": 5.2500,
    "AccountNumber": 12345,
    "RegisterId": 100,
    "HolderTypeName": "Individual"
  }
]

5. Get Holder By Unit Percent

NITECH Endpoint: GetHolderByUnitPercent

API Route: GET /api/registrars/getHolderByUnitPercent

Authentication: Not required

Request Parameters (Query):

Parameter Type Required Default Description
registerID int Yes - The register ID
asatDate string Yes - As-at date in yyyy-mm-dd format
xabove int No 0 Minimum units/percentage threshold
pageNumber int No 1 Page number for pagination
numberInPage int No 50 Number of records per page
byPercent bool No false If true, filter by percentage; if false, filter by units

Example: /api/registrars/getHolderByUnitPercent?registerID=100&asatDate=2024-09-18&xabove=1000&pageNumber=1&numberInPage=50&byPercent=false

Response:

[
  {
    "CompanyName": "string",
    "ShareHolderName": "string",
    "ShareHolderAddress": "string",
    "TotalUnits": 50000.00,
    "TotalUnitsDec": 50000.0000,
    "PercentUnits": 5.25,
    "PercentUnitsDec": 5.2500,
    "AccountNumber": 12345,
    "RegisterId": 100,
    "TotalPage": 10
  }
]

6. Get Total Holders Count By State

NITECH Endpoint: gettotalholderscount (with StateName output)

API Route: GET /api/registrars/getTotalHoldersCountByState

Authentication: Not required

Request Parameters (Query):

Parameter Type Required Default Description
registerID int Yes - The register ID
asatDate string Yes - As-at date in yyyy-mm-dd format
active bool No true Filter by active holders

Example: /api/registrars/getTotalHoldersCountByState?registerID=100&asatDate=2024-09-18&active=true

Response:

[
  {
    "Units": 500000.00,
    "TotalCount": 150,
    "StateName": "Lagos"
  }
]

Updated Endpoints

Get Holder Dividend Details

NITECH Endpoint: getholderdividenddetails

API Route: GET /api/registrars/getHolderDiv (existing)

Changes Made:

  1. Added new parameter: CloseStatus
  2. Updated endpoint URL from GetHolderDividendDetails to getholderdividenddetails

New Parameter:

Parameter Type Required Default Description
CloseStatus int No 0 Filter by close status: 0 = All, 1 = Not Closed, 2 = Closed

Updated Response Fields:

  • Verified (bool)
  • Reissue (bool)
  • DateVerified (string)
  • DateReissue (string)
  • DividendClosed (bool)
  • DateClosed (string)

Existing Endpoints (No Changes)

The following endpoints were already implemented and match the NITECH specification:

Endpoint API Route Description
ValidateUser Internal Authentication - returns WebToken
GetMandatedAccountsByRegisterId GET /api/registrars/getMandatedAccountsByRegisterId Get mandated accounts by register
GetHolderKYC GET /api/registrars/getHolderKYC Get holder KYC details
GetHolderTotalUnit GET /api/registrars/getHolderTotalUnit Get holder total units
GetHolderCertificateHistory GET /api/registrars/getHolderCert Get holder certificate history
GetMandatedHolderWithUnpaidDividend POST /api/registrars/getMandatedHolderWithUnpaidDividend Get holders with unpaid dividends
GetDividendDetailsByRegisterAndPayNumber GET /api/registrars/getDividendDetailsByRegisterAndPayNumber Get dividend details
GetWarrantEReplaceList POST /api/registrars/getWarrantEReplaceList Get warrant replacement list
GetCompanyInfo GET /api/registrars/ixtracRegister Get company/register information
GetEdividendPayments POST /api/registrars/getEDividendPayments Get e-dividend payments
UpdateHolderMandate POST /api/registrars/updateKYCMandate Update holder mandate
InsertOnlineDematShareholder POST /api/registrars/onlineDematShareholder Insert demat shareholder
InsertOnlineDematCertificate POST /api/registrars/onlineDematCertificate Insert demat certificate
gettotalholderscount GET /api/registrars/getTotalHoldersCount Get total holders count
gettopxshareholdersbyholding GET /api/registrars/getTopShareholdersByHolding Get top shareholders
getdividendhistorybyregisterid GET /api/registrars/getDividendHistoryByRegisterId Get dividend history
UpdateHolderOldAccountNumber POST /api/registrars/updateHolderOldAccountNumber Update old account number

API Reference

Authentication

All NITECH API calls require two tokens:

  1. Tokenkey - Static API token from environment variable IXTRAC_TOKEN
  2. WebToken - Dynamic token obtained from ValidateUser endpoint

The system automatically handles token management internally.

Date Format

All date parameters must be in yyyy-mm-dd format (e.g., 2024-09-18).

Search Options

Several endpoints use a SearchOption parameter with the following values:

Code Description
A Account Number
N Shareholder Name
C Clearing Number (CSCS)
I RIN Number
P Phone Number
B BVN
R Register ID
O Old Account Number
E Email
T Holder Type ID

Warrant Types

Code Description
DW Dividend Warrant
IW Interest Warrant
RW Rights Warrant

Files Modified

1. app/services/IXTRACRequest.php

New Methods Added:

  • verifyShareholderWarrants($payload) - Line ~4339
  • getHolderTypes() - Line ~4370
  • getRegisterRange($payload) - Line ~4395
  • getHolderTypeAnalysis($payload) - Line ~4420
  • getHolderByUnitPercent($payload) - Line ~4445
  • getTotalHoldersCountByState($payload) - Line ~4480

Updated Methods:

  • GetHolderDiv($payload) - Added CloseStatus parameter, updated endpoint URL

2. app/models/registrarModel.php

New Methods Added:

  • verifyShareholderWarrants($payload) - Line ~3810
  • getHolderTypes() - Line ~3820
  • getRegisterRange($payload) - Line ~3835
  • getHolderTypeAnalysis($payload) - Line ~3850
  • getHolderByUnitPercent($payload) - Line ~3865
  • getTotalHoldersCountByState($payload) - Line ~3880

3. app/routes/api/registrar/registrar.php

New Routes Added:

  • POST /api/registrars/verifyShareholderWarrants - Line ~15115
  • GET /api/registrars/getHolderTypes - Line ~15170
  • GET /api/registrars/getRegisterRange - Line ~15200
  • GET /api/registrars/getHolderTypeAnalysis - Line ~15260
  • GET /api/registrars/getHolderByUnitPercent - Line ~15320
  • GET /api/registrars/getTotalHoldersCountByState - Line ~15400

Testing

Test New Endpoints

  1. Get Holder Types:

    curl -X GET "http://localhost/api/registrars/getHolderTypes"

  2. Get Register Range:

    curl -X GET "http://localhost/api/registrars/getRegisterRange?registerID=100&asatDate=2024-09-18"

  3. Get Holder Type Analysis:

    curl -X GET "http://localhost/api/registrars/getHolderTypeAnalysis?registerID=100&asatDate=2024-09-18"

  4. Get Holder By Unit Percent:

    curl -X GET "http://localhost/api/registrars/getHolderByUnitPercent?registerID=100&asatDate=2024-09-18&pageNumber=1&numberInPage=50"

  5. Get Total Holders Count By State:

    curl -X GET "http://localhost/api/registrars/getTotalHoldersCountByState?registerID=100&asatDate=2024-09-18"

  6. Verify Shareholder Warrants (requires auth):

    curl -X POST "http://localhost/api/registrars/verifyShareholderWarrants" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accountNumber": 12345, "registerID": 100, "warrantType": "DW"}'

Notes

  1. All new endpoints follow the existing code patterns and conventions in the codebase.
  2. Error handling is consistent with existing implementations using Guzzle exception handling.
  3. The ValidateUser endpoint is called automatically for each API request to obtain a fresh WebToken.
  4. Environment variable IXTRAC_BASE_URL should point to the NITECH InterfaceX API base URL.
  5. Environment variable IXTRAC_TOKEN should contain the static Tokenkey for authentication.

Contact

For questions or issues regarding this integration, contact the development team.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment