Fixed Deposit Guide

This guide explains how a customer locks an amount for a set period and earns interest, and shows which API call does each step
and which message you receive when something happens. 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 is a worked story: open, look, close early, maturity.

Part 4 shows the notifications you receive, with the exact message for each.

Parts 5 to 7 are for looking things up: every route, 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. Interest figures
are illustrative: the deposit product decides the rates and rules.

Related guides: recurring-deposits-guide.md, savings-guide.md.

1. Concepts in plain words

Word	What it means	Where you see it
Main account	The customer's ordinary savings account. The principal comes from it, and money from the deposit goes back to it.	`nuban` in every call
Fixed deposit (FD)	The customer locks one amount for a set period and earns interest on it.	`/core/fixed-deposits`
Deposit product	A template made by the bank: allowed amounts and periods, interest rates, early closure penalty.	`productId`
Principal	The amount put in.	`depositAmount`, `principal`
Maturity	The end of the period; the deposit has earned its full interest.	`maturityDate`, `maturityAmount`
Maturity instruction	What happens at maturity: pay out, pay to the main account, or reinvest.	`maturityInstruction`
Early closure	Closing before maturity; the bank may reduce the interest (a penalty). Preview first.	`early-closure`
Withholding tax	Tax taken from interest, shown separately.	`withholdingTaxDeducted`

2. How the fixed deposit 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 deposits; if it is not you
get 401 with Access Denied or No Access To Core Banking. Contact the bank's support.

2.2 The customer rule

Every call names the customer's main account by nuban (in the body on POST and PUT, in the query on GET and DELETE).
The deposit must belong to the owner of that account. A deposit that belongs to someone else is a 404 Deposit Account Not Found,
exactly as if it did not exist.

2.3 The one deposit identifier: `accountNo`

A deposit is addressed by its account number (accountNo), the same number you see on the customer's statement. Use the
accountNo returned when you open the deposit. Other ids in responses are for the bank's own use and are never accepted as input.

2.4 Dates and amounts

Dates are yyyy-MM-dd; a date that is not a real date (for example 2026-02-31) is refused with 400. A date you leave out
defaults to today. Amounts are plain numbers in naira, at least 0.01.

2.5 Periods

depositPeriodFrequencyId: 0 days, 1 weeks, 2 months, 3 years.

2.6 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".
401	Access Denied / No Access To Core Banking	Your merchant is not set up for this call.
404	Deposit Account Not Found	The `accountNo` is not a deposit of this customer.
404	Savings account with external identifier ... does not exist	The `nuban` matches no account.
4xx	(the bank's own message)	A business rule: wrong status, amount outside the product limits, not enough balance, and so on.

2.7 Repeating a call safely

There is no idempotency key. Before you repeat a call that may have worked, read the deposit and the main account's transactions first.

3. Life of a fixed deposit

Open -> Active -> either Matured (at the end of the period) or Closed (early closure, or after maturity).
Opening takes one call: the deposit is created, approved and activated, and the principal moves from the main account.

Step 1. See the products

GET /core/fixed-deposits/products lists them; GET /core/fixed-deposits/products/{productId} shows one (interest slabs, allowed
periods, minimum and maximum deposit, early closure penalty). Choose a productId.

Step 2. Open the deposit

POST /core/fixed-deposits

{
  "nuban": "1234567890",
  "productId": 4,
  "depositAmount": 100000,
  "depositPeriod": 12,
  "depositPeriodFrequencyId": 2,
  "maturityInstruction": "TRANSFER_TO_MAIN_ACCOUNT",
  "transferInterestToMainAccount": false
}

Field	Meaning
`nuban`	Main account. The principal is taken from it.
`maturityInstruction`	`WITHDRAW_DEPOSIT` (pay out), `TRANSFER_TO_MAIN_ACCOUNT`, `REINVEST_PRINCIPAL_AND_INTEREST` or `REINVEST_PRINCIPAL_ONLY`.
`transferInterestToMainAccount`	Optional. `true` credits interest to the main account as it is posted.

Response (shortened): the new deposit as the bank holds it.

{
  "id": 9,
  "accountNo": "000000009",
  "status": { "id": 300, "code": "savingsAccountStatusType.active", "value": "Active" },
  "depositAmount": 100000,
  "depositPeriod": 12,
  "nominalAnnualInterestRate": 10,
  "maturityDate": [2027, 11, 10],
  "maturityAmount": 110000,
  "currency": { "code": "NGN" }
}

Keep accountNo.

Step 3. Look at the deposit

GET /core/fixed-deposits/000000009?nuban=1234567890

{
  "accountNo": "000000009",
  "status": { "id": 300, "code": "savingsAccountStatusType.active", "value": "Active" },
  "productName": "12 Month Fixed Deposit",
  "principal": 100000,
  "interestRate": 10,
  "depositPeriod": 12,
  "maturityDate": "2027-11-10",
  "maturityAmount": 110000,
  "interestSoFar": 2740.0,
  "interestPosted": 0,
  "withholdingTaxDeducted": 0,
  "accountBalance": 100000,
  "maturityInstruction": { "id": 200, "value": "Transfer to savings" },
  "currency": { "code": "NGN" }
}

Step 4. Close early: preview, then close

POST /core/fixed-deposits/000000009/early-closure/preview with

{ "nuban": "1234567890", "closedOnDate": "2026-11-10" }

returns what would be paid, with the penalty applied, and changes nothing (shortened):

{ "preClosurePenalApplicable": true, "preClosurePenalInterest": 1.0, "interestAccrued": 2200.5, "payoutAmount": 102200.5 }

POST /core/fixed-deposits/000000009/early-closure with the same body closes the deposit and pays the full amount to the main
account. Response (shortened): { "savingsId": 9, "resourceId": 9, "changes": { "status": { "value": "Premature Closed" } } }.
You also receive FD_PREMATURE_CLOSED (Part 4).

Step 5. Change what happens at maturity

PUT /core/fixed-deposits/000000009/maturity-instruction with { "nuban": "1234567890", "maturityInstruction": "WITHDRAW_DEPOSIT" }.
The bank only accepts this while the deposit is waiting for approval. On an active deposit you get the bank's refusal
(not.in.submittedandpendingapproval); choose the instruction when you open the deposit.

Step 6. At maturity

At the end of the period the bank's nightly job marks the deposit matured and you receive FD_MATURED. If the instruction was
transfer or reinvest, it is carried out in the same run (maturityInstructionApplied is true); otherwise the deposit stays
matured until the bank closes it (FD_CLOSED).

4. Notifications you receive

When something happens to a deposit, a message is placed on the same queue as your transaction messages. They are told apart by
eventType. Rules for all of them:

The queue is FIFO. The message group is the customer's main account nuban, and the deduplication id is eventId.

eventId is unique per event. Store it and ignore a message you have seen.

Delivery is best effort. A message that cannot be sent is logged on our side and not retried, so do not rely on notifications
alone: read the deposit if a message may have been missed.

Messages are sent after the action has completed, never for an action that failed.

Amounts are numbers in currency; dates are yyyy-MM-dd; timestamp is when the bank raised the event.

nuban is the customer's main account. depositAccountNo is the deposit's accountNo. amounts, dates and details contain only
the fields that apply.

Common shape:

Field	Meaning
`eventId`, `eventType`, `depositType`	The event, and `FIXED_DEPOSIT` or `RECURRING_DEPOSIT`.
`depositAccountNo`, `nuban`, `clientId`, `currency`	The deposit, its main account, the customer, the currency.
`amounts`, `dates`	Money and dates of the event.
`details`	`accountId`, `linkedSavingsAccountId`, `linkedSavingsAccountNo`, plus event specific fields. `onAccountClosureId` is `100` pay out, `200` transfer to savings, `300` reinvest principal and interest, `400` reinvest principal only.

4.1 `FD_MATURED`: a fixed deposit reached its maturity date

Sent by the nightly maturity job. maturityInstructionApplied is true when a transfer or reinvest instruction was carried out in the
same run; in that case there is no separate FD_CLOSED.

{
  "eventId": "3f1f0c9e-6a8f-4b6e-9a53-0f7c2d9a1b11",
  "eventType": "FD_MATURED",
  "depositType": "FIXED_DEPOSIT",
  "depositAccountNo": "000000009",
  "nuban": "1234567890",
  "clientId": 2048,
  "currency": "NGN",
  "amounts": { "depositAmount": 100000.0, "maturityAmount": 110000.0, "nominalAnnualInterestRate": 10.0, "accountBalance": 110000.0 },
  "dates": { "activationDate": "2026-01-01", "maturityDate": "2027-01-01" },
  "details": { "accountId": 9, "linkedSavingsAccountId": 5120, "linkedSavingsAccountNo": "000005120", "onAccountClosureId": 100, "maturityInstructionApplied": false },
  "timestamp": "2026-11-09T00:30:12Z"
}

4.2 `FD_PREMATURE_CLOSED`: a fixed deposit was closed before maturity

payoutAmount is what was paid out or transferred, interest and penalty included.

{
  "eventId": "3f1f0c9e-6a8f-4b6e-9a53-0f7c2d9a1b11",
  "eventType": "FD_PREMATURE_CLOSED",
  "depositType": "FIXED_DEPOSIT",
  "depositAccountNo": "000000009",
  "nuban": "1234567890",
  "clientId": 2048,
  "currency": "NGN",
  "amounts": { "depositAmount": 100000.0, "maturityAmount": 110000.0, "nominalAnnualInterestRate": 10.0, "payoutAmount": 102500.5 },
  "dates": { "activationDate": "2026-01-01", "maturityDate": "2027-01-01", "closedOnDate": "2026-11-09" },
  "details": { "accountId": 9, "linkedSavingsAccountId": 5120, "linkedSavingsAccountNo": "000005120", "onAccountClosureId": 200, "toSavingsAccountId": 5120 },
  "timestamp": "2026-11-09T14:02:51Z"
}

4.3 `FD_CLOSED`: a fixed deposit was closed (after maturity)

Same shape as 4.2 with "eventType": "FD_CLOSED", payoutAmount equal to the final balance and closedOnDate the closing date.

{
  "eventId": "9a3d5c10-2b7e-4e0a-8c64-51d9b0e7a2f3",
  "eventType": "FD_CLOSED",
  "depositType": "FIXED_DEPOSIT",
  "depositAccountNo": "000000009",
  "nuban": "1234567890",
  "clientId": 2048,
  "currency": "NGN",
  "amounts": { "depositAmount": 100000.0, "maturityAmount": 110000.0, "nominalAnnualInterestRate": 10.0, "payoutAmount": 110000.0 },
  "dates": { "activationDate": "2026-01-01", "maturityDate": "2027-01-01", "closedOnDate": "2027-01-02" },
  "details": { "accountId": 9, "linkedSavingsAccountId": 5120, "linkedSavingsAccountNo": "000005120", "onAccountClosureId": 100 },
  "timestamp": "2027-01-02T09:15:40Z"
}

5. Quick reference: every fixed deposit route

"Customer" is nuban: in the body on POST and PUT, in the query on GET. {no} is the deposit's accountNo.

Route	What it does	Key fields
`GET /core/fixed-deposits/products[/{productId}]`	List or read products
`POST /core/fixed-deposits`	Open (create, approve, activate)	`nuban`, `productId`, `depositAmount`, `depositPeriod`, `depositPeriodFrequencyId`, `maturityInstruction`, `transferInterestToMainAccount`
`GET /core/fixed-deposits/{no}`	Read	`nuban`
`POST /core/fixed-deposits/{no}/early-closure/preview`	Payout if closed now	`nuban`, `closedOnDate`
`POST /core/fixed-deposits/{no}/early-closure`	Close early, pay the main account	`nuban`, `closedOnDate`
`PUT /core/fixed-deposits/{no}/maturity-instruction`	Change the maturity instruction (pending deposits only)	`nuban`, `maturityInstruction`

6. 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 deposits for your merchant
`404 Deposit Account Not Found`	Wrong `accountNo`, or it belongs to another customer	Check the `accountNo` and `nuban` pair
`400` "`nuban` is required"	Missing customer	Send the main account `nuban`
`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 opening	Amount or period outside the product limits, or not enough balance	Read the product, and check the main account balance

1. Concepts in plain words#

2. How the fixed deposit APIs work#

2.1 Signing in#

2.2 The customer rule#

2.3 The one deposit identifier: accountNo#

2.4 Dates and amounts#

2.5 Periods#

2.6 Errors#

2.7 Repeating a call safely#

3. Life of a fixed deposit#

Step 1. See the products#

Step 2. Open the deposit#

Step 3. Look at the deposit#

Step 4. Close early: preview, then close#

Step 5. Change what happens at maturity#

Step 6. At maturity#

4. Notifications you receive#

4.1 FD_MATURED: a fixed deposit reached its maturity date#

4.2 FD_PREMATURE_CLOSED: a fixed deposit was closed before maturity#

4.3 FD_CLOSED: a fixed deposit was closed (after maturity)#

5. Quick reference: every fixed deposit route#

6. Common errors and what to do#