---
title: "Create balance [Beta]"
method: POST
path: "/v1/interest/balance"
tags: ["Interest engine"]
---

# Create balance \[Beta\]

`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

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](https://developers.pismo.io/events/docs/interest-engine-interest-balance-success-1) event when the balance is created successfully.
This endpoint generates an [Interest balance failed](https://developers.pismo.io/events/docs/interest-engine-interest-balance-failure-1) 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.

## Headers

- `content-type` string, required
- `authorization` string, required

## Request body

- InterestBalanceRequest
  - `balance_id` string, 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_id` string: Division ID. When not provided, defaults to `DEFAULT_DIVISION` internally.
  - `division_code` string: Optional division code. When provided, must be between 1 and 36 characters.
  - `account_id` string, number, required: Account ID. Must be between 1 and 64.
  - `external_account_id` string: External account ID managed by the requester
  - `interest_plan_id` string, UUID, required: Interest plan ID generated during the plan's creation. Must be an alphanumeric UUID with the alphabetical characters in lowercase.
  - `balance` number, double, required: Balance amount. Must be equal to or greater than zero.
  - `start_cycle_date` string, date, required: Start of the interest cycle. Format = YYYY-MM-DD.
  - `value_date` string, date, required: Deposit date. Format = YYYY-MM-DD.
  - `maturity_date` string, 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.

## Response `200`

OK

- InterestBalanceResponse
  - `program_id` string, required: Program ID
  - `balance_id` string, 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.
  - `external_account_id` string: External account ID managed by the requester

## Other responses

- `400`: Bad request
- `401`: Unauthorized access
- `404`: Not found
- `500`: Internal server error

---

[API](https://skmtc.dev/pismo/apis/banking-interest-operations.md) - [All operations](https://skmtc.dev/pismo/apis/banking-interest-operations/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/banking-interest-operations/revisions/a8e72194ee5e?raw)