Recurring Deposits

This guide explains how a customer saves a set amount on a regular schedule 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, pay instalments, withdraw, auto-debit, close early.

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: fixed-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. Instalments come from it, and withdrawals go back to it.	`nuban` in every call
Recurring deposit (RD)	The customer pays a set amount (an instalment) on a regular schedule for a set period and earns interest on the growing balance.	`/core/recurring-deposits`
Deposit product	A template made by the bank: allowed amounts and periods, interest rates, early closure penalty.	`productId`
Instalment	One payment into the deposit.	`installmentAmount`, `/instalments`
Missed instalment	An instalment still unpaid the day after its due date.	`RD_INSTALMENT_MISSED`
Auto-debit	A standing order that moves money from the main account into the deposit on a set day.	`/auto-debit`
Maturity	The end of the term. A recurring deposit is not paid out automatically; you are told it matured.	`maturityDate`, `RD_MATURED`
Early closure	Closing before maturity; the bank may reduce the interest. Preview first.	`early-closure`

2. How the recurring 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

termType: 0 days, 1 weeks, 2 months, 3 years. frequencyType (how often an instalment is due): 0 days, 1 weeks, 2 months.

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.
409	An auto-debit is already set up for this account	See 3.3.
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

reference on instalments and withdrawals is written into the transaction note so you can find it later. It is not checked for
duplicates. Before you repeat a call that may have worked, read the deposit and the main account's transactions first.

3. Life of a recurring deposit

Active -> Matured (end of term) or Closed (early closure or after maturity). Each instalment is a payment from the main account.

3.1 Products and opening

GET /core/recurring-deposits/products[/{productId}], then POST /core/recurring-deposits:

{
  "nuban": "1234567890",
  "productId": 6,
  "installmentAmount": 5000,
  "frequency": 1,
  "frequencyType": 2,
  "term": 12,
  "termType": 2,
  "firstInstalmentDate": "2026-12-01"
}

This means: 5,000 every 1 month, for 12 months, first due on 1 December. The response is the new deposit (shortened), with its
accountNo.

3.2 Look at the deposit

GET /core/recurring-deposits/000000010?nuban=1234567890 returns the deposit with its account figures (shortened):

{
  "accountNo": "000000010",
  "status": { "value": "Active" },
  "summary": { "accountBalance": 15000, "totalDeposits": 15000 },
  "recurringDetail": { "mandatoryRecommendedDepositAmount": 5000, "noOfOverdueInstallments": 0, "totalOverdueAmount": 0 },
  "maturityDate": [2027, 11, 1]
}

There is no instalment-by-instalment schedule in this response. The overdue figures only refresh when something touches the
account, so use RD_INSTALMENT_MISSED (Part 4) to learn about missed instalments.

3.3 Pay an instalment, withdraw, auto-debit

Call	Body	What happens
`POST /core/recurring-deposits/{accountNo}/instalments`	`{ "nuban", "amount", "reference" }`	Takes `amount` from the main account and pays it into the deposit as an instalment.
`POST /core/recurring-deposits/{accountNo}/withdrawals`	`{ "nuban", "amount", "reference" }`	Takes `amount` out of the deposit and credits the main account (if the product allows withdrawals).
`POST /core/recurring-deposits/{accountNo}/auto-debit`	`{ "nuban", "amount", "startDate", "endDate", "everyMonths" }`	Sets up a monthly standing order from the main account into the deposit on the day of `startDate`. `endDate` is optional; `everyMonths` defaults to 1.
`DELETE /core/recurring-deposits/{accountNo}/auto-debit?nuban=...`		Cancels it. `404 No auto-debit is set up` if there is none.

Example instalment: { "nuban": "1234567890", "amount": 5000, "reference": "INST-2026-12-001" }. It is two bank operations (take from the
main account, then pay into the deposit); if the second fails the first is reversed. If the reversal also fails, the main account
has been debited without the deposit being credited, so check both accounts before you retry.

Auto-debit and the schedule. An auto-debit moves money into the deposit like an ordinary transfer, which adds to the balance but
does not mark an instalment as paid. A customer who relies on auto-debit can still be shown as having missed instalments, and you
can still receive RD_INSTALMENT_MISSED. Pay instalments with the instalments call if the schedule matters to you.

3.4 Early closure

POST /core/recurring-deposits/{accountNo}/early-closure/preview and .../early-closure, same body as the fixed deposit
(nuban, optional closedOnDate). The payout goes to the main account. You receive RD_PREMATURE_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 `RD_MATURED`, `RD_PREMATURE_CLOSED`, `RD_CLOSED`

These three share one shape. RD_MATURED has no onAccountClosureId and maturityInstructionApplied is always false: a recurring deposit is not paid out automatically at maturity. payoutAmount is what was paid out or transferred on closure. Example, RD_PREMATURE_CLOSED:

{
  "eventId": "c04b7e55-1d2a-4f3b-9e8c-7a6d5b4c3e21",
  "eventType": "RD_PREMATURE_CLOSED",
  "depositType": "RECURRING_DEPOSIT",
  "depositAccountNo": "000000010",
  "nuban": "1234567890",
  "clientId": 2048,
  "currency": "NGN",
  "amounts": { "depositAmount": 15000.0, "maturityAmount": 62000.0, "nominalAnnualInterestRate": 8.0, "payoutAmount": 15200.0 },
  "dates": { "activationDate": "2026-09-01", "maturityDate": "2027-09-01", "closedOnDate": "2026-11-09" },
  "details": { "accountId": 10, "linkedSavingsAccountId": 5120, "linkedSavingsAccountNo": "000005120", "onAccountClosureId": 200, "toSavingsAccountId": 5120 },
  "timestamp": "2026-11-09T14:02:51Z"
}

4.2 `RD_INSTALMENT_PAID`: money was paid into a recurring deposit

Sent when a payment is made through the deposit's own payment (the instalments call, and the first payment when the deposit is
activated). Auto-debit transfers do not send it.

{
  "eventId": "e1a7b8c2-5d3f-4a9b-8c1e-2f4d6a8b0c13",
  "eventType": "RD_INSTALMENT_PAID",
  "depositType": "RECURRING_DEPOSIT",
  "depositAccountNo": "000000010",
  "nuban": "1234567890",
  "clientId": 2048,
  "currency": "NGN",
  "amounts": { "depositAmount": 15000.0, "maturityAmount": 62000.0, "nominalAnnualInterestRate": 8.0, "amountPaid": 5000.0, "accountBalance": 15000.0, "instalmentAmount": 5000.0 },
  "dates": { "activationDate": "2026-09-01", "maturityDate": "2027-09-01", "transactionDate": "2026-11-09" },
  "details": { "accountId": 10, "linkedSavingsAccountId": 5120, "linkedSavingsAccountNo": "000005120", "transactionId": 555 },
  "timestamp": "2026-11-09T10:21:07Z"
}

4.3 `RD_INSTALMENT_MISSED`: an instalment is still unpaid the day after its due date

Sent once per instalment by a daily job (about 01:00). A part-paid instalment counts as missed; amountOutstanding is what is still
owed. Only instalments that fell due in the last 7 days are announced.

{
  "eventId": "5d1e9f3a-7b2c-4c8d-a6e0-9b1f3d5a7c29",
  "eventType": "RD_INSTALMENT_MISSED",
  "depositType": "RECURRING_DEPOSIT",
  "depositAccountNo": "000000010",
  "nuban": "1234567890",
  "clientId": 2048,
  "currency": "NGN",
  "amounts": { "instalmentAmount": 5000.0, "amountPaid": 1000.0, "amountOutstanding": 4000.0 },
  "dates": { "dueDate": "2026-11-01" },
  "details": { "accountId": 10, "linkedSavingsAccountId": 5120, "linkedSavingsAccountNo": "000005120", "instalmentNumber": 3, "scheduleId": 211 },
  "timestamp": "2026-11-02T00:30:12Z"
}

5. Quick reference: every recurring deposit route

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

Route	What it does	Key fields
`GET /core/recurring-deposits/products[/{productId}]`	List or read products
`POST /core/recurring-deposits`	Open	`nuban`, `productId`, `installmentAmount`, `frequency`, `frequencyType`, `term`, `termType`, `firstInstalmentDate`
`GET /core/recurring-deposits/{no}`	Read	`nuban`
`POST /core/recurring-deposits/{no}/instalments`	Pay an instalment from the main account	`nuban`, `amount`, `reference`
`POST /core/recurring-deposits/{no}/withdrawals`	Withdraw to the main account	`nuban`, `amount`, `reference`
`POST /core/recurring-deposits/{no}/auto-debit`	Set up a monthly standing order	`nuban`, `amount`, `startDate`, `endDate`, `everyMonths`
`DELETE /core/recurring-deposits/{no}/auto-debit`	Cancel it	`nuban`
`POST /core/recurring-deposits/{no}/early-closure/preview` and `/early-closure`	Payout if closed now; close early	`nuban`, `closedOnDate`

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`
`409 An auto-debit is already set up`	One exists for this deposit	Cancel it first, then set up the new one
`404 No auto-debit is set up`	Nothing to cancel	None
`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 paying	Amount outside the product limits, or not enough balance	Check the product and the main account balance

1. Concepts in plain words#

2. How the recurring 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 recurring deposit#

3.1 Products and opening#

3.2 Look at the deposit#

3.3 Pay an instalment, withdraw, auto-debit#

3.4 Early closure#

4. Notifications you receive#

4.1 RD_MATURED, RD_PREMATURE_CLOSED, RD_CLOSED#

4.2 RD_INSTALMENT_PAID: money was paid into a recurring deposit#

4.3 RD_INSTALMENT_MISSED: an instalment is still unpaid the day after its due date#

5. Quick reference: every recurring deposit route#

6. Common errors and what to do#