CoreWave API Channel Documentation (Super Detailed)

Version: v1
Last Updated: 2026-03-03

This document is the implementation-level API reference for the API channel in this repository.

Export API Reference (.json) for Postman

0. Read This First (10-Second Mode)

0.1 Minimal Copy/Paste Bootstrap Calls

Authenticate:

curl --location '{{baseurl}}/api/auth/v1/authenticate' \
--header 'Content-Type: application/json' \
--data '{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET"
}'

Template secured call:

curl --location '{{baseurl}}/api/account/v1/searchaccount?PageNumber=1&PageSize=10' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'request-reference: req-001-unique' \
--header 'Content-Type: application/json'

Hard health-check call (simple + safe):

curl --location '{{baseurl}}/api/product/v1/searchproducts?PageNumber=1&PageSize=1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'request-reference: req-002-unique' \
--header 'Content-Type: application/json'

---

1. Platform Conventions

1.1 Base Pattern

• Route pattern: /api/{module}/v1/{action}
• Example: /api/account/v1/createcustomeraccount

1.2 Authorization

• Authenticate via /api/auth/v1/authenticate with clientId and clientSecret.
• Use Authorization: Bearer {token} on secured endpoints.
• API-channel policy requires actor_type=api_client claim.

1.3 API Key Inactivity Rule

• Unused API clients are auto-deactivated after 14 days.

1.4 Common Headers

• Authorization: bearer {token}
• Content-Type: application/json
• request-reference: {unique_value} (recommended)

1.5 Amount Unit

• Monetary values are in Naira (not kobo).

1.6 Institution-Level Integration Config

• Bills, Transfer, and Card integrations are configured per institution in Configuration.
• Shared gateway keys are appsettings fallback only.

---

2. Authentication (AUTH)

Base route: /api/auth/v1

2.1 POST /authenticate

Request:

{
  "clientId": "string",
  "clientSecret": "string"
}

Success:

{
  "accessToken": "string",
  "tokenType": "Bearer",
  "expirationTime": 1700000000,
  "tokenValiditySec": 3600
}

---

3. Module Order (Folder Alphabetical)

1. Accounts (/api/account/v1)
2. Account Lien (/api/accountlien/v1)
3. Account Overdraft (/api/accountoverdraft/v1)
4. Bills (/api/bills/v1)
5. Cards (/api/card/v1)
6. Fixed Deposits (/api/fixeddepositaccount/v1)
7. Limits (/api/limit/v1)
8. Loans (/api/loanaccount/v1)
9. Operations (/api/operations/v1)
10. Postings (/api/postings/v1)
11. Product (/api/product/v1)
12. Report (/api/report/v1)
13. Transfer (/api/transfer/v1)

---

4. Endpoint Inventory (Complete)

Folder	Method	Endpoint
Auth	POST	/api/auth/v1/authenticate
Account	POST	/api/account/v1/createcustomeraccount
Account	POST	/api/account/v1/createaccount
Account	POST	/api/account/v1/creategroupcustomerinformation
Account	PUT	/api/account/v1/updatecustomeraccount
Account	PUT	/api/account/v1/updatecustomerinformation
Account	PUT	/api/account/v1/updategroupcustomerinformation
Account	PUT	/api/account/v1/activate
Account	PUT	/api/account/v1/deactivate
Account	PUT	/api/account/v1/unfreeze
Account	GET	/api/account/v1/searchaccount
Account	GET	/api/account/v1/getaccountbalancebyaccountnumber
Account	GET	/api/account/v1/getbyaccountnumber
Account	GET	/api/account/v1/getextendedbalancebyaccountnumber
Account	GET	/api/account/v1/searchaccountofficers
Account	GET	/api/account/v1/searchgroupcustomers
Account	GET	/api/account/v1/searchindividualcustomers
Account	GET	/api/account/v1/listbranches
Account	GET	/api/account/v1/searchbranches
Account	POST	/api/account/v1/createvirtualaccount
AccountLien	POST	/api/accountlien/v1/placelien
AccountLien	POST	/api/accountlien/v1/updatelien
AccountLien	POST	/api/accountlien/v1/unplacelien
AccountOverdraft	POST	/api/accountoverdraft/v1/add
AccountOverdraft	PUT	/api/accountoverdraft/v1/update
AccountOverdraft	PUT	/api/accountoverdraft/v1/activate
AccountOverdraft	PUT	/api/accountoverdraft/v1/deactivate
AccountOverdraft	GET	/api/accountoverdraft/v1/search
Bills	GET	/api/bills/v1/billers
Bills	GET	/api/bills/v1/getcustomerinformation
Bills	POST	/api/bills/v1/vend
Bills	POST	/api/bills/v1/tsq
Bills	GET	/api/bills/v1/gettoken
Bills	GET	/api/bills/v1/search
Card	GET	/api/card/v1/searchcards
Card	POST	/api/card/v1/addcardtoaccount
Card	PUT	/api/card/v1/interswitch/updatecardchannelaccess
Card	GET	/api/card/v1/providus/searchcards
Card	PUT	/api/card/v1/providus/setcardpin
Card	PUT	/api/card/v1/providus/blockunblockcard
Card	PUT	/api/card/v1/block
Card	PUT	/api/card/v1/unblock
Card	DELETE	/api/card/v1/delete/{id}
FixedDepositAccount	POST	/api/fixeddepositaccount/v1/add
FixedDepositAccount	POST	/api/fixeddepositaccount/v1/topup
FixedDepositAccount	POST	/api/fixeddepositaccount/v1/liquidate
FixedDepositAccount	PUT	/api/fixeddepositaccount/v1/update
FixedDepositAccount	GET	/api/fixeddepositaccount/v1/search
Limit	PUT	/api/limit/v1/addupdateaccountlimit
Limit	GET	/api/limit/v1/getaccountlimit
LoanAccount	POST	/api/loanaccount/v1/add
LoanAccount	POST	/api/loanaccount/v1/disburseloan
LoanAccount	POST	/api/loanaccount/v1/repayloan
LoanAccount	POST	/api/loanaccount/v1/earlyrepaymentloan
LoanAccount	POST	/api/loanaccount/v1/addgrouploan
LoanAccount	POST	/api/loanaccount/v1/disbursegrouploan
LoanAccount	POST	/api/loanaccount/v1/repaygrouploan
LoanAccount	PUT	/api/loanaccount/v1/update
LoanAccount	GET	/api/loanaccount/v1/search
LoanAccount	GET	/api/loanaccount/v1/viewloanschedule
LoanAccount	GET	/api/loanaccount/v1/searchgrouploan
LoanAccount	GET	/api/loanaccount/v1/grouploancreditbureau
LoanAccount	GET	/api/loanaccount/v1/grouploanaireview
LoanAccount	GET	/api/loanaccount/v1/loancreditbureau
LoanAccount	GET	/api/loanaccount/v1/loanaireview
Operations	GET	/api/operations/v1/searchtillaccounts
Operations	GET	/api/operations/v1/gettillbalancebyaccountnumber
Operations	POST	/api/operations/v1/uploaddocument
Operations	PUT	/api/operations/v1/deletedocument
Operations	POST	/api/operations/v1/sendsms
Operations	POST	/api/operations/v1/sendemail
Postings	POST	/api/postings/v1/closeaccount
Postings	POST	/api/postings/v1/posttransaction
Postings	POST	/api/postings/v1/post
Postings	POST	/api/postings/v1/reversetransaction
Product	GET	/api/product/v1/searchproducts
Report	GET	/api/report/v1/requestcustomeraccountstatement
Report	GET	/api/report/v1/exportcustomerstatement
Report	GET	/api/report/v1/gettransactionreceipt
Report	GET	/api/report/v1/requestcustomeraccounthistoryreport
Report	GET	/api/report/v1/gettransactioncalloverreport
Report	GET	/api/report/v1/getloanexpectationreport
Report	GET	/api/report/v1/getloantrackingreport
Report	GET	/api/report/v1/getsavingsaccrualhistory
Transfer	GET	/api/transfer/v1/banks
Transfer	GET	/api/transfer/v1/nameenquiry
Transfer	GET	/api/transfer/v1/nameenquiry/local
Transfer	POST	/api/transfer/v1/balanceenquiry
Transfer	POST	/api/transfer/v1/localfundtransfer
Transfer	POST	/api/transfer/v1/outwardtransfer
Transfer	POST	/api/transfer/v1/fundstransfer
Transfer	GET	/api/transfer/v1/tsq
Transfer	GET	/api/transfer/v1/tsq/local
Transfer	GET	/api/transfer/v1/search

---

5. Virtual Account Contract Notes (/api/account/v1)

5.1 Create Virtual Account

Endpoint: POST /api/account/v1/createvirtualaccount

Request fields:

• Required: accountName, lastName, firstName, phoneNumber, email
• Conditional: parentAccountNumber is required unless API key is already bound to a parent account.
• Optional: referenceNumber, alias, otherNames, bvn, nin, maritalStatus, religion, homeTown, dateOfBirth, nationality, state, lga, identificationType, identificationNumber, pep, tin, employeeID, address, ignorePrefix, isBusinessAccount, accountType, paymentAmount, enhancedVirutalProxyPaymentDetails

Type mapping:

• accountType=0 -> VirtualProxy
• accountType=1 -> VirtualWallet
• accountType=2 -> EnhancedVirtualProxy (requires paymentAmount > 0)

Business rules:

• Parent settlement account must be corporate.
• ProductID/productCode is not used for virtual account creation.
• referenceNumber must be unique when provided.
• Response data.accountNumber is the generated virtual account number.

enhancedVirutalProxyPaymentDetails item shape:

{
  "accountNumber": "1000000001",
  "amount": 1500
}

5.2 Virtual Account Retrieval Behavior

GET /api/account/v1/getbyaccountnumber?AccountNumber={virtualAccountNumber} returns:

• isVirtualAccount=true
• virtualAccountID (virtual-account internal ID)
• settlementAccountNumber (parent account number)
• id resolved as virtual-account ID for virtual queries

GET /api/account/v1/getaccountbalancebyaccountnumber?AccountNumber={virtualAccountNumber} returns:

• accountNumber (queried virtual account number)
• settlementAccountNumber (parent account number)
• isVirtualAccount=true

GET /api/account/v1/searchaccount?AccountNumber={virtualAccountNumber}:

• Supports virtual-account fallback when no regular account row matches.
• Virtual rows include id, accountNumber, settlementAccountNumber, isVirtualAccount=true.

5.3 Virtual Account Update/State Operations

PUT /api/account/v1/updatecustomeraccount:

• id must be a numeric internal ID.
• id can be a regular account ID or virtual-account ID.
• Virtual-account updates require API bypass approvals enabled.

PUT /api/account/v1/activate, deactivate, unfreeze:

• Accept virtual account number as accountNumber.
• Operate on the parent settlement account state.

6. Public Integration Notes

Detailed source appendices have been removed from this public documentation.

For safe integration, use:

• Endpoint inventory in section 4.
• Execution workflows in API Channel Execution Guide.
• Live request testing in API Playground.

If your team needs institution-specific field clarifications, request support through your CoreWave integration contact.