Interest engine

Create balance [Beta]

Register a balance for an interest-bearing account using a previously configured interest plan to determine applicable interest rates.

This endpoint generates an Interest balance succeeded event when the balance is created successfully. This endpoint generates an Interest balance failed event when balance operation fails.

The event payload includes: program_id, balance_id, account_id, interest_plan_id, balance, start_cycle_date, value_date, maturity_date, and trigger_reason. The optional field external_account_id is included in the event only when present in the request. The division fields division_id and division_code are included in the event only when a non-default division is provided. They are omitted when division_id is DEFAULT_DIVISION or the value is null.

The optional field external_account_id is only returned in the response when present in the request.

The optional field trigger_reason indicates why the balance registration is being triggered. When omitted or null, it defaults to CYCLE_CLOSING. RETROACTIVE_CYCLE_CLOSING is only valid when value_date is before the current date. Otherwise, the request is rejected with a 400 error.

balance_id must be a valid UUID. Alphabetical characters are accepted in either case on input, but are converted to lowercase in the response.

post/v1/interest/balance

Request

Base URL
https://sandbox.pismolabs.io/interest-engine
URL
https://sandbox.pismolabs.io/interest-engine/v1/interest/balance
Auth
HTTP bearer

Headers

content-typestring required

Content type

authorizationstring required

Authorization

Request body

balance_idstring UUID required

Unique identifier for the balance, generated by the client. Must be a valid UUID. Alphabetical characters are accepted in either case on input, but are converted to lowercase in the response.

division_idstring

Division ID. When not provided, defaults to DEFAULT_DIVISION internally.

division_codestring

Optional division code. When provided, must be between 1 and 36 characters.

account_idstring number required

Account ID. Must be between 1 and 64.

external_account_idstring

External account ID managed by the requester

interest_plan_idstring UUID required

Interest plan ID generated during the plan's creation. Must be an alphanumeric UUID with the alphabetical characters in lowercase.

balancenumber double required

Balance amount. Must be equal to or greater than zero.

start_cycle_datestring date required

Start of the interest cycle. Format = YYYY-MM-DD.

value_datestring date required

Deposit date. Format = YYYY-MM-DD.

maturity_datestring date required

Deposit maturity date. Format = YYYY-MM-DD.

trigger_reason'CYCLE_CLOSING' | 'RETROACTIVE_CYCLE_CLOSING'

Reason that triggers the balance registration. Defaults to CYCLE_CLOSING when omitted or null. RETROACTIVE_CYCLE_CLOSING requires value_date to be before the current day. Otherwise, the request is rejected with a 400 error.

Example request

{
  "balance_id": "3f1c2b7a-9d4e-4a6b-8c21-5e7f9a0b1c2d",
  "division_id": "123",
  "division_code": "DIV-001",
  "account_id": "4040",
  "external_account_id": "4141",
  "interest_plan_id": "df3f3e3e-62d3-4323-902e-6ae6cc210f49",
  "balance": 23.95,
  "start_cycle_date": "2025-07-17",
  "value_date": "2025-07-17",
  "maturity_date": "2026-05-27",
  "trigger_reason": "CYCLE_CLOSING"
}

Response

program_idstring required

Program ID