--- title: "Simulate penalty" method: POST path: "/v1/deposits/accounts/{accountId}/penalty-simulation" tags: ["Penalty"] --- # Simulate penalty `POST /v1/deposits/accounts/{accountId}/penalty-simulation` ## Request - Base URL: `https://sandbox.pismolabs.io/savings-products` - URL: `https://sandbox.pismolabs.io/savings-products/v1/deposits/accounts/{accountId}/penalty-simulation` - Auth: HTTP bearer Simulate the penalty applied to a specified withdrawal on a given date. The operation is read‑only and does not modify any data. Use this endpoint to preview penalty fees before making an actual withdrawal. The simulation evaluates all penalty rules configured in the product, including: - Early withdrawal penalties - Grace period penalties - Tiered interest forfeiture penalties - Withdrawal fees - Subsequent withdrawal penalties Notes: - `withdrawal_date` must be the current date (UTC); past and future dates are rejected. - A withdrawal date inside the cool‑off period, or an inactive penalty record, returns `penalty_amount: 0` and `net_amount` = `gross_amount`, with `penalty_rule_applied`, `penalty_breakdown` and `currency` omitted. - The account balance comes from [Get transaction banking account balance](ref:get-account-balances): `book_balance` for `DEPOSIT_BASIS` products, or the `balance_type` balance for `BALANCE_BASIS` products. When `withdrawal_amount` is omitted, the account balance is used as the withdrawal amount. `withdrawal_amount` cannot exceed the account balance. - `gross_amount` reflects the account's resolved balance until a capitalization total record becomes available. ## Path parameters - `accountId` string, required ## Request body - PenaltySimulationRequest - `withdrawal_date` string, date-time, required: The simulated withdrawal date in ISO 8601 format. The value must match the current UTC date. Requests that use a past date return error `EIBACC0294`, while requests that use a future date return error `EIBACC0407`. - `withdrawal_amount` number, float: The amount to withdraw. When omitted, the account balance is used: `book_balance` for `DEPOSIT_BASIS` products, or the `balance_type` balance for `BALANCE_BASIS` products. The amount provided cannot exceed that balance. ## Response `200` Simulation completed successfully - PenaltySimulationResponse - `external_account_id` string: External account ID assigned by the client. Returned only when present on the account. - `withdrawal_amount` number: The withdrawal amount used in the simulation. (Equals the account balance when not passed in the request.) - `withdrawal_date` string, date-time: The withdrawal date used in the simulation in ISO 8601 format. - `penalty_rule_applied` PenaltyRuleApplied[]: List of penalty rules applied to the withdrawal, omitted when no penalty applies. Every non-zero `penalty_breakdown` component has at least one matching rule: a `FIXED` rule for `fixed_amount` and a `PERCENTAGE` rule for `percentage_amount`. - `type` 'PERCENTAGE' | 'FIXED': The penalty calculation type. - `PERCENTAGE`: The penalty calculated as a percentage of the withdrawal amount - `FIXED`: The penalty is a fixed amount - `value` number, float: The penalty value. For `PERCENTAGE`, this represents the percentage rate with up to 4 decimal places. For example, `2.5` = 2.5% and `0.0671` = 0.0671%. It is the exact rate used to calculate the penalty, which is not rounded before it is applied to the `withdrawal_amount`. For `FIXED`, this is the absolute amount in the account's currency with two decimal places. - `description` string: Type of penalty rule applied, represented by one of the following constants: - `WITHDRAWAL_FEE` - `EARLY_WITHDRAWAL_AFTER_OPENING` - `GRACE_PERIOD` - `TIERED_INTEREST_FORFEITURE` - `WITHDRAWAL` - `penalty_amount` number: The total penalty applied to the withdrawal. Always equals the sum of the `penalty_breakdown` components (`fixed_amount` + `percentage_amount`). Returns `0` when no penalties are triggered or during the cool-off period. - `penalty_breakdown` PenaltyBreakdown: Breakdown of `penalty_amount` by calculation type, where `fixed_amount` + `percentage_amount` = `penalty_amount`. Each non-zero component corresponds to a rule of the same type in `penalty_rule_applied`. Omitted when no penalty applies. - `fixed_amount` number: The sum of all `FIXED`-type penalties. Corresponds to the `FIXED` entries in `penalty_rule_applied`. - `percentage_amount` number: The sum of all percentage-based penalties. Each percentage penalty is `rule.value` % of the `withdrawal_amount`. (The documented base is the withdrawal amount.) Only the sum is rounded to 2 decimal places. - `currency` string: The 3-letter currency code in ISO 4217 alphabetic format, omitted if no penalty applies. - `gross_amount` number: Gross amount of the deposit account. When a capitalization total record exists, this value equals the principal balance plus the total accrued interest. Before the first capitalization event, when no capitalization total record is available, the amount derives from the balance specified by `balance_type` (`VALUE_DATED_BALANCE` or `LEDGER_BALANCE`), or from the book balance for deposit-based accruals. Because it reflects the total value of the deposit account, it does not necessarily equal `withdrawal_amount` + `interest_earned_amount`. - `interest_earned_amount` number: Total interest earned through interest payments or capitalization. Returns `0` if no interest has been paid or capitalized. A positive `gross_amount` does not necessarily indicate earned interest, as it also reflects the account balance. - `net_amount` number: Amount remaining after penalties are deducted from the gross amount, calculated as `net_amount` = `gross_amount` - `penalty_amount`. This value is non-negative when `withdrawal_amount` does not exceed the resolved balance. When the penalty amount is `0`, `net_amount` equals `gross_amount` and `penalty_rule_applied` is omitted. - `simulation_timestamp` string, date-time: The date and time of the simulation, formatted according to ISO 8601. ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found - `422`: Unprocessable Entity - `500`: Internal Server Error --- [API](https://skmtc.dev/pismo/apis/banking-interest-bearing-accounts.md) - [All operations](https://skmtc.dev/pismo/apis/banking-interest-bearing-accounts/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/banking-interest-bearing-accounts/revisions/c68f61feb8a8?raw)