---
updatedAt: 2026-05-06T17:23:53.000Z
agentTools:
  siteIndex: https://developers.pismo.io/llms.txt
  projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---

# Simulate penalty

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:
- A withdrawal date inside the cool‑off period results in no penalties
- If `withdrawal_amount` is omitted, the Pismo platform fetches the current book balance from [Get transaction banking account balance](ref:get-account-balances).
- If `withdrawal_amount` is provided, the balance cannot exceed the current book balance.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Banking - Interest-bearing accounts",
    "version": "1.0.0",
    "description": "API for interest-bearing account functionality",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/savings-products",
      "description": "Sandbox API server for testing"
    }
  ],
  "tags": [
    {
      "name": "Penalty",
      "description": "Endpoints that manage penalties for deposit accounts"
    }
  ],
  "components": {
    "parameters": {
      "accountIdentifier": {
        "description": "Account ID. Accepts either the Pismo `account_id` or your `external_account_id`. Send the same ID used to generate the access token.\n",
        "in": "path",
        "name": "accountId",
        "required": true,
        "schema": {
          "type": "string",
          "maxLength": 60
        },
        "example": "123456"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error type code",
            "example": "EIBACC0003"
          },
          "details": {
            "type": "string",
            "description": "Error details",
            "example": "error EIBACC0008: Validation error [(Field 'Order' is invalid)]"
          },
          "message": {
            "description": "Error message",
            "example": "Bad Request",
            "type": "string"
          }
        }
      },
      "PenaltySimulationRequest": {
        "type": "object",
        "required": [
          "withdrawal_date"
        ],
        "properties": {
          "withdrawal_amount": {
            "type": "number",
            "description": "The amount the customer intends to withdraw. When omitted, the system fetches the current book balance from Bank Statements API. When provided, it must not exceed the current book balance.\n",
            "example": 5000
          },
          "withdrawal_date": {
            "type": "string",
            "format": "date-time",
            "description": "Simulated withdrawal date in ISO 8601 format.",
            "example": "2026-06-15T00:00:00Z"
          }
        }
      },
      "PenaltySimulationResponse": {
        "type": "object",
        "properties": {
          "external_account_id": {
            "type": "string",
            "description": "External account identifier of the resolved account. Returned only when the account has an external account identifier.",
            "example": "a4070788-bbe3-4127-8abc-12345"
          },
          "withdrawal_amount": {
            "type": "number",
            "description": "The withdrawal amount used in the simulation (equals book_balance when omitted in request)",
            "example": 40667.17
          },
          "withdrawal_date": {
            "type": "string",
            "format": "date-time",
            "description": "The withdrawal date used in the simulation in ISO 8601 format.",
            "example": "2026-12-15T00:00:00Z"
          },
          "penalty_rule_applied": {
            "type": "array",
            "description": "List of penalty rules that applies to the withdrawal, omitted if no penalties apply.\n",
            "items": {
              "$ref": "#/components/schemas/PenaltyRuleApplied"
            }
          },
          "penalty_amount": {
            "type": "number",
            "description": "The total penalty amount applied to the withdrawal, combining all relevant penalty rules.",
            "example": 231.75
          },
          "penalty_breakdown": {
            "$ref": "#/components/schemas/PenaltyBreakdown"
          },
          "currency": {
            "type": "string",
            "description": "The currency in ISO 4217 alphabetic format, omitted if no penalty applies.",
            "example": "BRL"
          },
          "gross_amount": {
            "type": "number",
            "description": "The gross amount of the deposit account, calculated as the sum of the total balance without interest plus the total interest earned. Always present; 0 when no total record exists.\n",
            "example": 41329.34
          },
          "interest_earned_amount": {
            "type": "number",
            "description": "The total interest earned (paid/capitalized) on the account. Always present; 0 when no total record exists.\n",
            "example": 667.17
          },
          "net_amount": {
            "type": "number",
            "description": "The net amount after deducting penalties from the gross amount: `gross_amount - penalty_amount`.\n",
            "example": 41097.59
          },
          "simulation_timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time of the simulation, formatted according to ISO 8601.",
            "example": "2026-06-19T19:22:55Z"
          }
        }
      },
      "PenaltyRuleApplied": {
        "type": "object",
        "description": "A single penalty rule applied during a simulated withdrawal",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "PERCENTAGE",
              "FIXED"
            ],
            "description": "The penalty calculation type.\n- `PERCENTAGE`: The penalty calculated as a percentage of the withdrawal amount\n- `FIXED`: The penalty is a fixed amount\n",
            "example": "PERCENTAGE"
          },
          "value": {
            "type": "number",
            "format": "float",
            "description": "The penalty value. For `PERCENTAGE`, this represents the percentage rate. For example, `2.5` = 2.5%. For `FIXED`, this is the absolute amount in the account's currency.\n",
            "example": 2.5
          },
          "description": {
            "type": "string",
            "description": "Describes the penalty rule that triggers the penalty",
            "example": "Early withdrawal after opening penalty"
          }
        }
      },
      "PenaltyBreakdown": {
        "type": "object",
        "description": "Breakdown of the total penalty amount by calculation type. Omitted when no penalty applies.",
        "properties": {
          "fixed_amount": {
            "type": "number",
            "description": "The sum of all fixed-amount penalties",
            "example": 50
          },
          "percentage_amount": {
            "type": "number",
            "description": "The sum of all percentage-based penalties",
            "example": 75.5
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/v1/deposits/accounts/{accountId}/penalty-simulation": {
      "post": {
        "tags": [
          "Penalty"
        ],
        "summary": "Simulate penalty",
        "description": "Simulate the penalty applied to a specified withdrawal on a given date. The operation is read‑only and does not modify any data.\n\nUse this endpoint to preview penalty fees before making an actual withdrawal.\n\nThe simulation evaluates all penalty rules configured in the product, including:\n\n- Early withdrawal penalties\n\n- Grace period penalties\n\n- Tiered interest forfeiture penalties\n\n- Withdrawal fees\n\n- Subsequent withdrawal penalties\n\nNotes:\n- A withdrawal date inside the cool‑off period results in no penalties\n- If `withdrawal_amount` is omitted, the Pismo platform fetches the current book balance from [Get transaction banking account balance](https://developers.pismo.io/pismo-docs/reference/get-account-balances).\n- If `withdrawal_amount` is provided, the balance cannot exceed the current book balance.\n",
        "operationId": "interest-bearing-v1-simulate-penalty",
        "parameters": [
          {
            "$ref": "#/components/parameters/accountIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PenaltySimulationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulation completed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PenaltySimulationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "invalidAccountId": {
                    "summary": "Invalid account ID path parameter",
                    "value": {
                      "code": "EIBACC0015",
                      "message": "Invalid accountId path param"
                    }
                  },
                  "invalidWithdrawalAmount": {
                    "summary": "Invalid withdrawal amount (zero or negative)",
                    "value": {
                      "code": "EIBACC0008",
                      "message": "Validation error",
                      "details": "withdrawal_amount requires a positive number"
                    }
                  },
                  "missingWithdrawalDate": {
                    "summary": "Missing withdrawal date",
                    "value": {
                      "code": "EIBACC0008",
                      "message": "Validation error",
                      "details": "withdrawal_date is required"
                    }
                  },
                  "invalidWithdrawalDate": {
                    "summary": "Invalid withdrawal date format",
                    "value": {
                      "code": "EIBACC0008",
                      "message": "Validation error",
                      "details": "withdrawal_date must be a valid ISO 8601 datetime (e.g. 2026-01-15T15:00:00Z)"
                    }
                  },
                  "withdrawalAmountExceedsBalance": {
                    "summary": "Withdrawal amount exceeds book balance",
                    "value": {
                      "code": "EIBACC0338",
                      "message": "withdrawal_amount cannot be greater than the account balance",
                      "details": "available balance: 40667.17"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "missingTenantHeader": {
                    "summary": "Missing tenant header",
                    "value": {
                      "code": "EIBACC0005",
                      "message": "Missing required header: 'x-tenant'"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "accountNotFound": {
                    "summary": "Account not found",
                    "value": {
                      "code": "EIBACC0226",
                      "message": "Account not found"
                    }
                  },
                  "productNotAttached": {
                    "summary": "Product is not attached to account",
                    "value": {
                      "code": "EIBACC0064",
                      "message": "Product not found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "withdrawalDateInPast": {
                    "summary": "Withdrawal date set in the past",
                    "value": {
                      "code": "EIBACC0294",
                      "message": "withdrawalDate must not be in the past"
                    }
                  },
                  "productNotDeposit": {
                    "summary": "Product is not a deposit product",
                    "value": {
                      "code": "EIBACC0295",
                      "message": "Penalty simulation is only available for deposit accounts"
                    }
                  },
                  "noPenaltyConfigured": {
                    "summary": "No penalty configured for simulation",
                    "value": {
                      "code": "EIBACC0296",
                      "message": "No penalty is configured for the product attached to this account"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "internalError": {
                    "summary": "Internal error",
                    "value": {
                      "code": "EIBACC0007",
                      "message": "Internal error"
                    }
                  },
                  "getPenaltyError": {
                    "summary": "Get penalty error",
                    "value": {
                      "code": "EIBACC0204",
                      "message": "Get Penalty error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}
```