Settlement Processing

Settlement batches aggregate interbank transactions at end-of-day (EOD) and post the corresponding GL entries. Each batch tracks its lifecycle from generation through final settlement with the Central Bank.

How Settlement Batches Work

At the close of each business day, the settlement service:

1. Aggregates all completed interbank transactions by counterparty bank.
2. Generates a settlement batch per bank with net debit/credit positions.
3. Posts GL journal entries to move funds from in-transit to clearing accounts.
4. Marks the batch as settled once CBN confirmation is received.

EOD Trigger
  │
  ▼
Generate Batches ──▶ PENDING
  │
  ▼
Process (GL Post) ──▶ PROCESSING ──▶ POSTED
  │
  ▼
CBN Confirmation ──▶ SETTLED

Settlement Batch Statuses

Status	Description
PENDING	Batch generated, awaiting GL posting
PROCESSING	GL entries are being created and posted
POSTED	GL entries posted successfully
SETTLED	CBN settlement confirmed
FAILED	Processing failed — eligible for retry

Generate a Settlement Batch

Generates batches for all interbank transactions on the specified date.

POST /api/v1/settlements/generate

cURL

curl -X POST https://api.korastratum.com/api/v1/cba/settlements/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: demo_bank" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-04-07"
  }'

Node.js

const batches = await cbaRequest("POST", "/api/v1/settlements/generate", token, {
  date: "2026-04-07",
});

Python

batches = cba_request("POST", "/api/v1/settlements/generate", token, {
    "date": "2026-04-07",
})

Go

body := map[string]string{"date": "2026-04-07"}
batches, err := cbaRequest(ctx, "POST", "/api/v1/settlements/generate", token, body)

Response:

{
  "batches": [
    {
      "id": "batch-uuid-1",
      "settlement_date": "2026-04-07",
      "counterparty_bank_code": "058",
      "counterparty_bank_name": "Guaranty Trust Bank",
      "total_outbound": 15000000.00,
      "total_inbound": 8500000.00,
      "net_position": -6500000.00,
      "transaction_count": 342,
      "status": "PENDING",
      "created_at": "2026-04-07T23:00:00Z"
    }
  ],
  "total_batches": 12
}

Process a Batch (GL Posting)

Posts the GL journal entries for a settlement batch. This creates double-entry records moving funds from the NIP in-transit account to the CBN clearing account.

POST /api/v1/settlements/:id/process

cURL

curl -X POST https://api.korastratum.com/api/v1/cba/settlements/batch-uuid-1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: demo_bank"

Node.js

const result = await cbaRequest("POST", "/api/v1/settlements/batch-uuid-1/process", token);

Python

result = cba_request("POST", "/api/v1/settlements/batch-uuid-1/process", token)

Go

result, err := cbaRequest(ctx, "POST", "/api/v1/settlements/batch-uuid-1/process", token, nil)

GL Entries Created

For each processed batch, the service creates a balanced journal:

Entry	Account	Code	Type
Debit	NIP In-Transit	1200-012	Asset (clearing)
Credit	CBN NIP Clearing	1200-010	Asset (clearing)

note

The GL accounts 1200-012 (NIP In-Transit) and 1200-010 (CBN NIP Clearing) are pre-seeded during tenant provisioning. Do not modify these accounts without coordinating with your operations team.

Retry a Failed Batch

If processing fails (e.g., GL service timeout), retry the batch:

POST /api/v1/settlements/:id/retry

cURL

curl -X POST https://api.korastratum.com/api/v1/cba/settlements/batch-uuid-1/retry \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: demo_bank"

Node.js

const result = await cbaRequest("POST", "/api/v1/settlements/batch-uuid-1/retry", token);

Python

result = cba_request("POST", "/api/v1/settlements/batch-uuid-1/retry", token)

Go

result, err := cbaRequest(ctx, "POST", "/api/v1/settlements/batch-uuid-1/retry", token, nil)

warning

Retry is idempotent — calling it on an already-posted batch returns the existing result. Only batches with status FAILED will be reprocessed.

List Settlement Batches

GET /api/v1/settlements?date=2026-04-07&status=PENDING

Query parameters:

Parameter	Type	Description
date	string	Filter by settlement date (YYYY-MM-DD)
status	string	Filter by status: PENDING, PROCESSING, POSTED, SETTLED, FAILED
bank_code	string	Filter by counterparty bank CBN code
limit	integer	Page size (default 20, max 100)
cursor	string	Pagination cursor

Get a Single Batch

GET /api/v1/settlements/:id

Returns full batch details including the list of transactions and GL journal references.

Next Steps

• NIP Transfers — Outbound and inbound NIP transfer flows.
• General Ledger — Journal posting and chart of accounts.
• Financial Reports — Trial balance and settlement reconciliation.