Saving Account Guide

This guide explains the customer's savings account from the first call to the last: opening and activating an account, looking at it,
moving money, protecting it (blocks and holds), and how its interest is earned, read, posted and reported. It also explains the
message you receive when interest is posted, and how to close an account. You do not need to know anything about banking or this API
before you start.

Part 1 explains the words used everywhere else.

Part 2 explains the rules every call follows.

Part 3 shows how an account moves from one state to the next.

Part 4 is a worked story: one customer gets an account, and you look at it.

Part 5 covers money in and out, and the account's history.

Part 6 covers protecting an account: limits, blocks and holds.

Parts 7 to 9 cover interest, the savings product, and closing an account.

Part 10 shows the message you receive when interest is posted.

Parts 11 to 13 are for looking things up: every route in one table, common errors, and things worth knowing.

All example data is made up. All money is in naira (NGN). Responses marked (shortened) show the fields you will use; the real
response has more fields. Interest figures are illustrative: the savings product decides the rates.

Related guides: fixed-deposits-guide.md, recurring-deposits-guide.md, loans-guide.md.

1. Concepts in plain words

Word	What it means	Where you see it
Customer	The person or business the account belongs to. A customer has a `clientId`.	`clientId`
Savings account	The ordinary account a customer keeps money in. A customer can have more than one.	`nuban`
NUBAN	The 10-digit account number. It is how you name an account in nearly every call.	`nuban`
Savings product	A template made by the bank: currency, interest rate, minimum balance, charges. Every account is created from one.	`productId` (ask the bank which ids you may use)
Activation	A new customer is not active until the bank (or you, through the API) activates them.	`/core/account/activate/{clientId}`
KYC level	How well the customer has been verified. The level sets what the account may do.	`kycLevel`
Current and available balance	Current is what the account holds. Available is what can be used right now: current balance less holds.	`currentBalance`, `availableBalance`
Block	Stops the account from being used: all movement, only money in (credit), or only money out (debit).	`block`, `block-credit`, `block-debit`
Hold (lien)	Sets aside an amount so it cannot be spent, without blocking the whole account.	`hold-amount`
Transaction limit	A cap on how much can leave the account in one transaction or in one day.	`singleTransactionLimit`, `dailyTransactionLimit`
Interest accrued	Interest earned so far but not yet added to the balance.	`interestAccrued`
Interest posting	The bank adds the accrued interest to the balance, usually once a month.	`interestPostings`, `Interest posting`
Withholding tax	Tax taken from the interest when it is posted, shown as a separate debit.	`withholdingTaxDeductions`, `Withhold Tax`
Overdraft interest	Interest charged on an overdrawn account.	`Overdraft interest`
Main account	The customer's ordinary savings account; a closed account's balance goes to it.	`mainNuban`

2. How the savings APIs work

All routes are under {tpGatewayHostUrl}.

2.1 Signing in

Every call uses the same bearer token as the other /core routes. Your merchant account must be set up for these calls; if it is not you
get 401 with Access Denied or No Access To Core Banking. Contact the bank's support.

2.2 How an account is named

An account is named by its nuban (10 digits): in the path on GET routes and in the body on POST and PUT. A customer is named by
clientId. Other ids in responses are for the bank's own use and are never accepted as input, except clientId, productId and the hold
holdTransactionId described below.

2.3 Dates and amounts

Dates are yyyy-MM-dd, except dateOfBirth when you create a customer and startDate and endDate on the transaction history, which are dd-MM-yyyy. A date you leave out defaults to today.
Amounts are plain numbers in naira, at least 0.01.

2.4 Errors

Errors use the same body as the rest of the API. The ones you will meet most:

Status	Message	Meaning
400	The Following Parameters Contain Errors	A field is missing or wrong; `parameters` names it, for example "`nuban` is required".
400	`clientType` must be PERSON or BUSINESS	When creating an account.
401	Access Denied / No Access To Core Banking	Your merchant is not set up for this call.
403	Post No Debit Already Placed On Account	A hold was asked to respect a debit block, and the account already has one.
404	Savings account with external identifier ... does not exist	The `nuban` matches no account.
4xx	(the bank's own message)	A business rule: account not active, amount over a limit, not enough balance, and so on.

2.5 Repeating a call safely

There is no idempotency key on account calls. Before you repeat a call that may have worked, read the account first (GET /core/account/{nuban}).
reference on closing is used for the balance transfer and is not checked for duplicates.

3. The life of a savings account

create customer + account -> activate customer -> use (credit, debit, history) -> close
                                   |
                       block / block-credit / block-debit  <->  unblock
                       hold-amount  <->  release-amount

A new customer and their first account are created together. The account can be used once the customer is active.

An account can be blocked fully, for credits only or for debits only, and unblocked again. A hold sets an amount aside until you release it.

An account is closed by moving its balance to the customer's main account (Part 9).

4. The running story: Ada's savings account

Step 1. Create the customer and the account

POST /core/account

{
  "clientType": "PERSON",
  "firstname": "Ada",
  "lastname": "Obi",
  "email": "ada.obi@example.com",
  "mobileNo": "08031234567",
  "bvn": "22212345678",
  "dateOfBirth": "14-03-1990",
  "genderId": 1,
  "productId": 2
}

Field	Rules
`clientType`	`PERSON` or `BUSINESS`. A person needs `firstname` and `lastname`; a business needs `fullName`.
`mobileNo`	Required.
`bvn` or `nin`	One of them is required.
`productId`	Required, 1 or greater: the savings product for the first account.
`nuban`	Optional. If you send one it must be 10 digits; otherwise the bank issues one.
`genderId`, `dateOfBirth`, `address`, `stateId`, `addressTypeId`	Optional details about the customer.
`registrationNumber`	For businesses.

Response (shortened): the customer and their new account.

{
  "clientType": "PERSON",
  "fullName": "Ada Obi",
  "mobileNo": "08031234567",
  "nuban": "1234567890",
  "clientId": 2048,
  "productId": 2,
  "productName": "Regular Savings",
  "productCurrency": "NGN",
  "active": false
}

POST /core/client takes the same body and does the same thing. Keep clientId and nuban.

Step 2. Activate the customer

POST /core/account/activate/2048, with an optional body { "activationFeeCollected": true }. Send true when you have already
collected the account's activation fee; leave it out to let the bank charge it from the account. The response confirms the
activation. The activation date is today.

Step 3. Find an account

GET /core/account/1234567890 returns one account (shortened):

{
  "clientId": 2048,
  "nuban": "1234567890",
  "fullName": "Ada Obi",
  "mobileNo": "08031234567",
  "productName": "Regular Savings",
  "productCurrency": "NGN",
  "currentBalance": 50000.0,
  "availableBalance": 50000.0,
  "kycLevel": 1,
  "active": true,
  "singleTransactionLimit": 100000.0,
  "dailyTransactionLimit": 500000.0
}

You can also look an account up by something the customer knows. POST /core/account/find with any of email, mobileNo, nin, bvn,
nuban, externalId or active, and the optional query parameters accounts=true (include each customer's accounts) and
transactions=true (include recent transactions), returns the matching customers as a list. GET /core/account/bvn/{bvn} returns
the accounts for a BVN.

Step 4. All of a customer's accounts

GET /core/accounts/{clientId}: every account the customer has, with balances.

GET /core/summary/{clientId}: the accounts, the ten most recent transactions, and a summary for the week: total credits, total debits, and the number of completed, pending and failed transactions.

GET /core/account/fulldetails/{clientId} and GET /core/account/fulldetailsbynuban/{nuban}: the customer's complete profile with accounts. Optional type and showsenstivedata query parameters choose what is included.

Step 5. Open another account for the same customer

POST /core/account/add with { "clientId": 2048, "productId": 3, "activationFeeCollected": true } opens a further account (new nuban)
for an existing customer. activationFeeCollected is optional.

Step 6. Change the customer's details

PUT /core/account takes the same fields as the create body; send clientId and only the fields you want to change.
To update one detail only, use POST /core/account/updatebvn, /updatenin or /updatekyc (the body names the customer and the new value). PUT /core/account/{clientId}/notifications switches
the customer's emailNotification and smsNotification on or off.

5. Money in and out

5.1 Credit (money in)

POST /core/credit

{
  "nuban": "1234567890",
  "amount": 5000,
  "paymentTypeId": 1,
  "note": "Salary top-up"
}

amount must be at least 0.01, and paymentTypeId (1 or greater) names the payment type; get the ids from GET /core/paymenttypes.
note is optional. The response returns the transaction (shortened):

{
  "id": 918001,
  "nuban": "1234567890",
  "amount": 5000.0,
  "transactionType": "Deposit",
  "transactionDate": "2026-11-10",
  "balance": 55000.0,
  "currency": "NGN",
  "note": "Salary top-up"
}

5.2 Debit (money out)

POST /core/debit with the same body takes money out and returns the transaction ("transactionType": "Withdrawal"). It fails with the bank's
own message if the account is blocked for debits, the balance is too low, or a limit would be exceeded.

5.3 Work out the charges first

POST /core/account/calculatecharges with { "nuban": "1234567890", "amount": 5000, "transactionType": "OUTWARD" } (INWARD or OUTWARD)
returns totalCharges and a list of charges (name, amount). It changes nothing.

5.4 Transaction history

GET /core/transactions/{nuban}?startDate=01-11-2026&endDate=30-11-2026 lists the account's transactions, newest first; both dates are optional and use the format dd-MM-yyyy.

GET /core/transactions lists every transaction the gateway has recorded, newest first.

GET /core/transactions/details/{accountId}/{transactionId} reads one transaction (add ?intraBank=true for a transfer between accounts in the bank), and GET /core/transactionsdetails/{transactionId} reads one by its transaction id alone.

Each transaction has id, nuban, amount, transactionType, transactionDate, balance (after it), currency, note and, for transfers, transferDetails.

5.5 Moving money to another account

Transfers (to another account in the bank, to another bank, or to a virtual account) are separate routes under /core/transfer.

6. Protecting an account: limits, blocks and holds

6.1 Transaction limits

POST /core/account/{clientId}/transactionlimit

{ "nuban": "1234567890", "singleTransactionLimit": 100000, "dailyTransactionLimit": 500000 }

Sets how much can leave the account in one transaction and in one day. Send either or both.

6.2 Blocks

Each takes { "nuban": "1234567890", "reasonForBlock": "Suspected fraud" } (reason up to 100 characters); every unblock takes only nuban.

Call	Effect	Undo
`POST /core/account/block`	Stops all use of the account	`POST /core/account/unblock`
`POST /core/account/block-credit`	Stops money coming in	`POST /core/account/unblock-credit`
`POST /core/account/block-debit`	Stops money going out	`POST /core/account/unblock-debit`

6.3 Holds

POST /core/account/hold-amount

{ "nuban": "1234567890", "amount": 20000, "reasonForBlock": "Card authorisation", "transactionDate": "2026-11-10", "lienAllowed": false, "enforcePND": true }

Field	Meaning
`amount`	At least `0.01`. Set aside, so the available balance drops by this amount.
`reasonForBlock`	Required, up to 100 characters.
`transactionDate`	Optional, defaults to today.
`lienAllowed`	Optional. `true` lets the hold exceed what can be withdrawn (the product must allow it).
`enforcePND`	Optional. `true` refuses the hold with `403 Post No Debit Already Placed On Account` if the account is already blocked for debits.

The response carries the hold's id in resourceId. Keep it: you need it to release the hold.

POST /core/account/release-amount with { "nuban": "1234567890", "holdTransactionId": 918050 } lifts the hold.

7. Reading interest

GET /core/account/1234567890/interest?fromDate=2026-01-01&toDate=2026-10-31 (dates optional):

{
  "nuban": "1234567890",
  "interestAccrued": 120.5,
  "totalInterestEarned": 1520.4,
  "totalInterestPosted": 1399.9,
  "totalWithholdingTaxDeducted": 139.99,
  "interestPostings": [ { "transactionId": 918273, "date": "2026-10-31", "amount": 152.4 } ],
  "withholdingTaxDeductions": [ { "transactionId": 918274, "date": "2026-10-31", "amount": 15.24 } ]
}

interestAccrued is earned but not yet posted. Reversed transactions are left out. When interest is posted you also receive a message on your queue (Part 10).

8. Savings product

GET /core/savings/products/{productId}: interest rate, minimum balance, lock-in period, withholding tax.

9. Closing a savings account

POST /core/account/1234567890/close

{ "mainNuban": "1234500000", "reference": "CLOSE-0001", "closedOnDate": "2026-11-10" }

Posts any unposted interest, moves the whole balance to mainNuban (which must belong to the same customer), then closes the account.
It is several bank operations, not one: if it fails after the transfer, the account is left open with a zero balance; repeat the same
call to finish.

10. The message you receive when interest is posted

Whenever interest is posted to a savings account, a fixed deposit or a recurring deposit, a message is placed on the same queue as your
transaction messages. The same applies to withholding tax and overdraft interest. Interest is posted by the bank's scheduled run,
usually once a month, or by a person posting it by hand; both send the same message.

Interest posting:

{
  "id": 918273,
  "nuban": "1234567890",
  "amount": 152.40,
  "note": "Interest posting for period ending 31-10-2026",
  "transactionDate": "2026-10-31",
  "transactionType": "Interest posting",
  "balance": 50152.40,
  "createdDate": "2026-11-01T01:05:12Z",
  "currency": "NGN",
  "clientName": "Ada Obi"
}

Withholding tax on the same interest:

{
  "id": 918274,
  "nuban": "1234567890",
  "amount": 15.24,
  "note": "Withholding tax on interest for period ending 31-10-2026",
  "transactionDate": "2026-10-31",
  "transactionType": "Withhold Tax",
  "balance": 50137.16,
  "createdDate": "2026-11-01T01:05:12Z",
  "currency": "NGN",
  "clientName": "Ada Obi"
}

For a fixed or recurring deposit the message has the same shape; nuban is the deposit's account, and balance is the deposit's balance.

11. Quick reference: every savings route

"Customer" is clientId. Account routes name the account by nuban.

Route	What it does	Key fields
`POST /core/account` (also `POST /core/client`)	Create a customer and their first account	`clientType`, names, `mobileNo`, `bvn` or `nin`, `productId`
`POST /core/account/activate/{clientId}`	Activate the customer	`activationFeeCollected`
`POST /core/account/add`	Open another account for a customer	`clientId`, `productId`, `activationFeeCollected`
`PUT /core/account`	Change customer details	`clientId`, fields to change
`POST /core/account/updatebvn`, `/updatenin`, `/updatekyc`	Update one detail
`PUT /core/account/{clientId}/notifications`	Email and SMS notifications on or off	`emailNotification`, `smsNotification`
`GET /core/account/{nuban}`	Read one account
`POST /core/account/find`	Find customers	`email`, `mobileNo`, `nin`, `bvn`, `nuban`, `externalId`, `active`; query `accounts`, `transactions`
`GET /core/account/bvn/{bvn}`	Accounts for a BVN
`GET /core/accounts/{clientId}`	All accounts of a customer
`GET /core/summary/{clientId}`	Accounts, recent transactions, weekly totals
`GET /core/account/fulldetails/{clientId}`, `/fulldetailsbynuban/{nuban}`	Full profile	`type`, `showsenstivedata`
`POST /core/credit`, `POST /core/debit`	Money in, money out	`nuban`, `amount`, `paymentTypeId`, `note`
`POST /core/account/calculatecharges`	Charges for a transaction	`nuban`, `amount`, `transactionType`
`GET /core/transactions/{nuban}`	Account history	`startDate`, `endDate` (`dd-MM-yyyy`)
`GET /core/transactions/details/{accountId}/{transactionId}`	One transaction	`intraBank`
`POST /core/account/{clientId}/transactionlimit`	Set limits	`nuban`, `singleTransactionLimit`, `dailyTransactionLimit`
`POST /core/account/block`, `/block-credit`, `/block-debit`	Block	`nuban`, `reasonForBlock`
`POST /core/account/unblock`, `/unblock-credit`, `/unblock-debit`	Unblock	`nuban`
`POST /core/account/hold-amount`	Hold an amount	`nuban`, `amount`, `reasonForBlock`, `transactionDate`, `lienAllowed`, `enforcePND`
`POST /core/account/release-amount`	Release a hold	`nuban`, `holdTransactionId`
`GET /core/account/{nuban}/interest`	Interest accrued, posted, tax	`fromDate`, `toDate`
`GET /core/savings/products/{productId}`	Savings product terms
`POST /core/account/{nuban}/close`	Post interest, move the balance to the main account, close	`mainNuban`, `reference`, `closedOnDate`

12. Common errors and what to do

You see	Why	What to do
`401 Access Denied` or `No Access To Core Banking`	Your merchant is not set up for this call	Ask the bank to enable it for your merchant
`400` "`bvn` or `nin` is required"	Neither was sent when creating an account	Send one of them
`400` "`clientType` must be PERSON or BUSINESS"	Missing or wrong `clientType`	Send `PERSON` or `BUSINESS`
`404 Savings account with external identifier ... does not exist`	The `nuban` matches no account	Check the `nuban`
`403 Post No Debit Already Placed On Account`	`enforcePND` was true and the account is blocked for debits	Unblock debits first, or send `enforcePND` false
`400` "`mainNuban` must be a different account"	Closing an account into itself	Send the customer's main account
`403 Main account does not belong to this customer`	`mainNuban` is another customer's	Send the same customer's account
`403 User has no authority to: <PERMISSION>`	The bank user behind your merchant may not do this	Ask the bank to grant the named permission
Bank's own `4xx` on credit or debit	Blocked account, low balance, limit exceeded, inactive customer	Read the account and its limits

1. Concepts in plain words#

2. How the savings APIs work#

2.1 Signing in#

2.2 How an account is named#

2.3 Dates and amounts#

2.4 Errors#

2.5 Repeating a call safely#

3. The life of a savings account#

4. The running story: Ada's savings account#

Step 1. Create the customer and the account#

Step 2. Activate the customer#

Step 3. Find an account#

Step 4. All of a customer's accounts#

Step 5. Open another account for the same customer#

Step 6. Change the customer's details#

5. Money in and out#

5.1 Credit (money in)#

5.2 Debit (money out)#

5.3 Work out the charges first#

5.4 Transaction history#

5.5 Moving money to another account#

6. Protecting an account: limits, blocks and holds#

6.1 Transaction limits#

6.2 Blocks#

6.3 Holds#

7. Reading interest#

8. Savings product#

9. Closing a savings account#

10. The message you receive when interest is posted#

11. Quick reference: every savings route#

12. Common errors and what to do#