CoreWave API Channel Documentation (Super Detailed)

Version: v1
Last Updated: 2026-05-31

This document is the API channel reference for external integrators.

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.
• Authenticated requests use Authorization: Bearer {token} on secured endpoints.

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.
• Bills, Transfer, and Card integrations are configured per institution.

---

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 (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. Entity Additional Metadata (/api/entity-additional-metadata/v1)
7. Fixed Deposits (/api/fixeddepositaccount/v1)
8. Limits (/api/limit/v1)
9. Loans (/api/loanaccount/v1)
10. Operations (/api/operations/v1)
11. Postings (/api/postings/v1)
12. Product (/api/product/v1)
13. Report (/api/report/v1)
14. 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
Agent	POST	/api/agent/v1/add
Agent	PUT	/api/agent/v1/update
Agent	PUT	/api/agent/v1/change-status
Agent	DELETE	/api/agent/v1/delete/{ID}
Agent	GET	/api/agent/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}
Integration	POST	/api/integrations/recova/v1/{institutionId}/SmsAlert
Integration	POST	/api/integrations/recova/v1/{institutionId}/LoanBalanceUpdate
Integration	GET	/api/integrations/recova/v1/{institutionId}/LoanDueAmount/{loanReference}
Integration	POST	/api/integrations/recova/v1/{institutionId}/MandateCreation
EntityAdditionalMetadata	GET	/api/entity-additional-metadata/v1/supported-entity-types
EntityAdditionalMetadata	GET	/api/entity-additional-metadata/v1/{entityType}/{entityId}
EntityAdditionalMetadata	PUT	/api/entity-additional-metadata/v1/{entityType}/{entityId}
EntityAdditionalMetadata	DELETE	/api/entity-additional-metadata/v1/{entityType}/{entityId}
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
FixedDepositAccount	GET	/api/fixeddepositaccount/v1/view-certificate/{ID}/{type}
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/view-certificate/{ID}
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
Utility	GET	/api/utility/v1/countries
Utility	GET	/api/utility/v1/regions
Utility	GET	/api/utility/v1/cities
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

---

Loan Certificate Retrieval

GET /api/loanaccount/v1/view-certificate/{ID} returns the loan offer/agreement document as a Base64 data URL in data.document.

Rules:

• ID is the loan ID returned from GET /api/loanaccount/v1/search.
• Optional query isRestructure=true switches lookup to a loan restructure ID.
• Response includes mimeType, fileName, loanAccountNumber, and document.

Fixed Deposit Certificate Retrieval

GET /api/fixeddepositaccount/v1/view-certificate/{ID}/{type} returns the fixed deposit certificate as a Base64 data URL in data.document.

Rules:

• ID is the fixed deposit ID returned from GET /api/fixeddepositaccount/v1/search.
• type must be PDF or Excel.
• Response includes contractNo, accountName, mimeType, fileName, and document.

Geography Lookup

Use these endpoints to populate country, region/state, and city/LGA dropdowns for API-driven onboarding flows.

• GET /api/utility/v1/countries
• GET /api/utility/v1/regions
• GET /api/utility/v1/cities

Rules:

• regions supports filtering by CountryID or CountryCode2.
• cities supports filtering by RegionID, RegionShortCode, and CountryCode2.
• For Nigeria, regions maps to states and cities can be used as LGA or city lookup data depending on your workflow.

Recova Integration Webhooks

These endpoints are intended for Recova callbacks and are scoped to the target institution in the route.

Authorization:

• Use Authorization: Bearer {RECUVA_WEBHOOK_SECRET}.
• This is the institution webhook secret configured in CoreWave.
• Do not use API-channel access tokens on these routes.

Webhook endpoints:

• POST /api/integrations/recova/v1/{institutionId}/SmsAlert
• POST /api/integrations/recova/v1/{institutionId}/LoanBalanceUpdate
• GET /api/integrations/recova/v1/{institutionId}/LoanDueAmount/{loanReference}
• POST /api/integrations/recova/v1/{institutionId}/MandateCreation

Sample request bodies:

POST /api/integrations/recova/v1/{institutionId}/SmsAlert

{
  "phoneNumber": "08000000000",
  "message": "Dear customer, your repayment is due.",
  "institutionCode": "INST001",
  "loanReference": "LN-0001"
}

POST /api/integrations/recova/v1/{institutionId}/LoanBalanceUpdate

{
  "loanReference": "LN-0001",
  "debitedAmount": 10000,
  "recoveryFee": 500,
  "settlementAmount": 9500,
  "transactionReference": "RCV-TRX-001",
  "narration": "Direct debit settlement",
  "institutionCode": "INST001"
}

POST /api/integrations/recova/v1/{institutionId}/MandateCreation

{
  "loanReference": "LN-0001",
  "institutionCode": "INST001"
}

GET /api/integrations/recova/v1/{institutionId}/LoanDueAmount/{loanReference} returns the current outstanding amount due for the supplied loan reference.

4.1 Agent Management Contract Notes (/api/agent/v1)

4.1 Add Agent

Endpoint: POST /api/agent/v1/add

Request fields:

• Required: name, branchCode
• Optional: phoneNumber, emailAddress, address, referenceNumber, notes

Business rules:

• Agent is a separate concept from account officer.
• Agent cannot log in to CoreWave.
• branchCode is the institution branch ID.
• CoreWave generates a unique institution-scoped agentCode.

4.2 Update or Suspend Agent

Endpoints:

• PUT /api/agent/v1/update
• PUT /api/agent/v1/change-status
• DELETE /api/agent/v1/delete/{ID}

Business rules:

• Delete is blocked once loans are attached to the agent.
• status accepts the staff-status values already used by the institution, such as Active or Suspended.
• Search results return agentCode, branchName, contact fields, and current status.

4.2 Loan Agent Attribution

Loan creation and updates support optional agent attribution:

• POST /api/loanaccount/v1/add
• PUT /api/loanaccount/v1/update
• GET /api/loanaccount/v1/search

Business rules:

• agentCode is optional.
• Agent is different from account officer; do not reuse accountOfficerCode for agent attribution.
• When supplied, agentCode must resolve to an active agent in the same institution.
• Loan search responses include agentCode, agentName, and agentID.

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

Business rules:

• Parent settlement account must be corporate.
• Virtual accounts are collection aliases for inbound NIBSS NIP/NPS funding only.
• Virtual accounts do not hold balances and cannot be used on debit legs.
• The effective display name returned on enquiry is {virtual account name}/{corporate customer name}.
• Only accountType=0 is supported. VirtualWallet and EnhancedVirtualProxy are legacy values and should not be sent for new integrations.
• ProductID/productCode is not used for virtual account creation.
• referenceNumber must be unique when provided.
• Response data.accountNumber is the generated virtual account number.

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
• accountName resolved as {virtual account name}/{corporate customer name}
• canHoldBalance=false
• canDebit=false
• historyMode=credits-only

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

• an error response because virtual accounts do not expose a standalone balance; query the settlement account directly.

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, and composite accountName.

5.3 Virtual Account History Reporting

GET /api/report/v1/requestcustomeraccounthistoryreport?AccountNumber={virtualAccountNumber} returns:

• credits only for that virtual account
• accountNumber resolved as the virtual account number
• settlementAccountNumber populated with the parent account
• isVirtualAccount=true

GET /api/report/v1/requestcustomeraccountstatement?AccountNumber={virtualAccountNumber} and GET /api/report/v1/exportcustomerstatement?AccountNumber={virtualAccountNumber}:

• return an error response because virtual accounts do not have standalone statements

5.4 Virtual Account Update/State Operations

PUT /api/account/v1/updatecustomeraccount:

• id must be a numeric internal ID.
• Virtual-account IDs are rejected because collection aliases are not updated through this endpoint.

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

• Reject virtual account numbers. Operate on the settlement account directly instead.

6. Entity Additional Metadata

Use /api/entity-additional-metadata/v1 to attach institution-specific JSON to supported records.

Supported entity types:

• account
• casa-product
• corporate-customer
• customer
• fixed-deposit
• fixed-deposit-product
• loan
• loan-product
• ledger
• placement

Endpoints:

• GET /api/entity-additional-metadata/v1/supported-entity-types
• GET /api/entity-additional-metadata/v1/{entityType}/{entityId}
• PUT /api/entity-additional-metadata/v1/{entityType}/{entityId}
• DELETE /api/entity-additional-metadata/v1/{entityType}/{entityId}

Rules:

• PUT accepts { "additionalMetadata": { ... } } or { "additionalMetadata": [ ... ] }.
• Objects may contain nested objects and arrays.
• PUT replaces the full stored value.
• Use DELETE to clear the value.
• The payload must not exceed 64 KB.
• API-channel token claims scope every read and write to one institution.

See Entity Extra Data for copy-ready requests, portal instructions, and response examples.

7. Public Integration Notes

7.1 Fraud Copilot AML hold response

When Fraud Copilot is enabled, transaction rules can stop API postings and transfers before balances move. A held request returns 202 Accepted with data.statusCode = "AML_HOLD" and data.amlApprovalReference.

After authorized staff approval, retry the same payload with:

{
  "amlApprovalReference": "AML-26caaadad76043d596bd"
}

The approval reference is payload-bound and one-time use. See Fraud Copilot AML Holds.

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.