> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pismo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:
- An active penalty waiver removes the waived penalties from the simulation
- A withdrawal date inside the cool‑off period results in no penalties
- If the account has an active penalty waiver, the waived penalties are excluded from the simulation
- If the withdrawal date falls within the cool-off period, no penalties apply


# OpenAPI definition

```json
{
  "openapi": "3.0.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": {
      "authorizationTokenHeader": {
        "name": "AuthorizationToken",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "required": true,
        "description": "Account token. Token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized error.\n",
        "example": 1234
      },
      "accountId": {
        "description": "Account ID",
        "in": "path",
        "name": "accountId",
        "required": true,
        "schema": {
          "type": "integer"
        },
        "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"
          }
        }
      },
      "PenaltySimulationResponse": {
        "type": "object",
        "properties": {
          "withdrawal_amount": {
            "type": "number",
            "description": "The withdrawal amount used in the simulation",
            "example": 5000
          },
          "withdrawal_date": {
            "type": "string",
            "format": "date",
            "description": "The withdrawal date used in the simulation, this must be in ISO 8601-compliant format.",
            "example": "2025-06-15T00:00:00.000Z"
          },
          "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": 125.5
          },
          "penalty_breakdown": {
            "$ref": "#/components/schemas/PenaltyBreakdown"
          },
          "currency": {
            "type": "string",
            "description": "The penalty amount in ISO 4217 format, omitted if no penalty applies.",
            "example": "USD"
          },
          "simulation_timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time of the simulation, formatted according to ISO 8601.",
            "example": "2025-01-23T13:26:25.000Z"
          }
        }
      },
      "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",
            "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": {
      "get": {
        "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- An active penalty waiver removes the waived penalties from the simulation\n- A withdrawal date inside the cool‑off period results in no penalties\n- If the account has an active penalty waiver, the waived penalties are excluded from the simulation\n- If the withdrawal date falls within the cool-off period, no penalties apply\n",
        "operationId": "interest-bearing-v1-simulate-penalty",
        "parameters": [
          {
            "$ref": "#/components/parameters/accountId"
          },
          {
            "$ref": "#/components/parameters/authorizationTokenHeader"
          },
          {
            "name": "withdrawalAmount",
            "in": "query",
            "required": true,
            "description": "The amount the customer intends to withdraw",
            "schema": {
              "type": "number"
            },
            "example": 5000
          },
          {
            "name": "withdrawalDate",
            "in": "query",
            "required": true,
            "description": "Simulated withdrawal date, this must be in ISO 8601 format.",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2025-06-15T00:00:00.000Z"
          }
        ],
        "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"
                    }
                  },
                  "missingWithdrawalAmount": {
                    "summary": "Missing withdrawal amount",
                    "value": {
                      "code": "EIBACC0008",
                      "message": "Validation error",
                      "details": "withdrawalAmount is required"
                    }
                  },
                  "invalidWithdrawalAmount": {
                    "summary": "Invalid withdrawal amount",
                    "value": {
                      "code": "EIBACC0008",
                      "message": "Validation error",
                      "details": "withdrawalAmount requires a positive number"
                    }
                  },
                  "missingWithdrawalDate": {
                    "summary": "Missing withdrawal date",
                    "value": {
                      "code": "EIBACC0008",
                      "message": "Validation error",
                      "details": "withdrawalDate is required"
                    }
                  },
                  "invalidWithdrawalDate": {
                    "summary": "Invalid withdrawal date format",
                    "value": {
                      "code": "EIBACC0008",
                      "message": "Validation error",
                      "details": "withdrawalDate must be a valid ISO 8601 datetime (e.g. 2026-01-15T15:00:00Z)"
                    }
                  }
                }
              }
            }
          },
          "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": []
    }
  ]
}
```