# Create penalty waiver

Creates a waiver for active penalties on a deposit account.
When a waiver is active, penalty fees are not applied during early withdrawals or other penalty-triggering events. For details about penalty waivers, refer to the [Penalty waivers](doc:penalties-for-cd-accounts#penalty-waivers) section of Penalties for CD accounts.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "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 waiver",
      "description": "Endpoints that manage penalty waivers 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"
          }
        }
      },
      "CreateWaiverRequest": {
        "type": "object",
        "required": [
          "reason"
        ],
        "properties": {
          "reason": {
            "type": "string",
            "maxLength": 100,
            "description": "Reason for creating the penalty waiver",
            "example": "Customer loyalty waiver"
          },
          "valid_until": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time when the waiver expires, in RFC 3339 format, for example `2024-12-31T23:59:59Z`. If not provided, the waiver does not expire. The value must be at least 1 minute later than the request time. When the waiver expires, all penalty fees that apply to the account are automatically restored, which is equivalent to calling the `DELETE` endpoint.\n",
            "example": "2024-12-31T23:59:59.000Z"
          },
          "exceptions": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "EARLY_WITHDRAWAL_AFTER_OPENING",
                "TIERED_INTEREST_FORFEITURE",
                "GRACE_PERIOD",
                "WITHDRAWAL_FEE",
                "WITHDRAWAL"
              ]
            },
            "description": "List of penalty types that are NOT waived (exceptions to the waiver).\nIf not provided, all penalty types are waived.\n\nThese values correspond to the penalty configurations defined in the product's `penalties` object. Refer to [Create deposit product](https://developers.pismo.io/pismo-docs/reference/interest-bearing-v1-create-deposit-product) for details.\n\n| Exception value | Product field |\n|-----------------|---------------|\n| `EARLY_WITHDRAWAL_AFTER_OPENING` | `penalties.early_withdrawal_after_opening` |\n| `TIERED_INTEREST_FORFEITURE` | `penalties.tiered_interest_forfeiture` |\n| `GRACE_PERIOD` | `penalties.grace_period` |\n| `WITHDRAWAL_FEE` | `penalties.withdrawal_fee` |\n| `WITHDRAWAL` | `penalties.subsequent_withdrawals` |\n\n**Note:** If an exception is specified for a penalty that is not configured in the product, the exception has no effect. Only penalties that are both configured in the product and included in the exception list continue to be applied.\n",
            "example": [
              "GRACE_PERIOD"
            ]
          }
        }
      },
      "CreateWaiverResponse": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "description": "Reason for the penalty waiver",
            "example": "Customer loyalty waiver"
          },
          "status": {
            "type": "string",
            "description": "The waiver status",
            "example": "WAIVED"
          },
          "applied_at": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time when the waiver was applied",
            "example": "2024-01-23T13:26:25.000Z"
          },
          "valid_until": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time when the waiver expires, in RFC 3339 format. If `null`, the waiver does not expire. When the waiver expires, all applicable penalty fees are automatically restored, which is equivalent to calling the `DELETE` endpoint.\n",
            "example": "2024-12-31T23:59:59.000Z"
          },
          "exceptions": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "EARLY_WITHDRAWAL_AFTER_OPENING",
                "TIERED_INTEREST_FORFEITURE",
                "GRACE_PERIOD",
                "WITHDRAWAL_FEE",
                "WITHDRAWAL"
              ]
            },
            "description": "List of penalty types that are not waived. \nThese values act as exceptions to the waiver. For the mapping between exception values and product penalty fields, refer to `CreateWaiverRequest.exceptions`.\n",
            "example": [
              "GRACE_PERIOD"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/v1/deposits/accounts/{accountId}/penalty/waive": {
      "post": {
        "tags": [
          "Penalty waiver"
        ],
        "summary": "Create penalty waiver",
        "description": "Creates a waiver for active penalties on a deposit account.\nWhen a waiver is active, penalty fees are not applied during early withdrawals or other penalty-triggering events. For details about penalty waivers, refer to the [Penalty waivers](https://developers.pismo.io/pismo-docs/docs/penalties-for-cd-accounts#penalty-waivers) section of Penalties for CD accounts.\n",
        "operationId": "interest-bearing-v1-create-penalty-waiver",
        "parameters": [
          {
            "$ref": "#/components/parameters/accountId"
          },
          {
            "$ref": "#/components/parameters/authorizationTokenHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWaiverRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Waiver created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateWaiverResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "validationError": {
                    "summary": "Validation error",
                    "value": {
                      "code": "EIBACC0003",
                      "message": "Bad Request",
                      "details": "error EIBACC0003: Validation error [(Field 'reason' is required)]"
                    }
                  },
                  "invalidAccountId": {
                    "summary": "Invalid account ID path parameter",
                    "value": {
                      "code": "EIBACC0015",
                      "message": "Invalid accountId path param"
                    }
                  },
                  "invalidValidUntil": {
                    "summary": "Invalid valid_until datetime",
                    "value": {
                      "code": "EIBACC0287",
                      "message": "Invalid valid_until datetime",
                      "details": "valid_until must be at least 1 minute in the future"
                    }
                  }
                }
              }
            }
          },
          "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": "EIBACC0234",
                      "message": "Account not found"
                    }
                  },
                  "penaltyNotFound": {
                    "summary": "Penalty not found or inactive",
                    "value": {
                      "code": "EIBACC0285",
                      "message": "Penalty not found or inactive for this account"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "waiverAlreadyExists": {
                    "summary": "Waiver already exists",
                    "value": {
                      "code": "EIBACC0286",
                      "message": "Waiver already exists for 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": "EIBACC0212",
                      "message": "Get Penalty error"
                    }
                  },
                  "scheduleError": {
                    "summary": "Failed to schedule waiver expiration",
                    "value": {
                      "code": "EIBACC0288",
                      "message": "Failed to schedule waiver expiration"
                    }
                  },
                  "missingFeeModel": {
                    "summary": "Penalty missing fee model",
                    "value": {
                      "code": "EIBACC0289",
                      "message": "Penalty is missing fee model ID"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}
```