--- updatedAt: 2026-06-17T17:50:44.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # List Org interest plans List all interest plans for a given Org. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Banking - Interest engine", "version": "1.0.0", "description": "API to handle interest-bearing account operations", "termsOfService": "https://developers.pismo.io/terms/", "contact": { "name": "API Support", "url": "https://developers.pismolabs.io/pismo-docs/docs/support" }, "license": { "name": "Copyright Pismo" } }, "servers": [ { "url": "https://sandbox.pismolabs.io/interest-engine", "description": "Sandbox API server for testing" }, { "url": "https://sandbox.pismolabs.io/passport/v2/s2s/access-token", "description": "Sandbox API for oauth2" } ], "tags": [ { "name": "Interest engine", "description": "Manage interest plans" } ], "components": { "parameters": { "PageNumber": { "name": "page", "in": "query", "required": true, "description": "Page number. Default is `1`.", "example": 1, "schema": { "type": "integer", "format": "int32" } }, "PerPage": { "name": "perPage", "in": "query", "required": true, "description": "Number of items per page. Default is `10`.", "example": 10, "schema": { "type": "integer", "format": "int32" } } }, "schemas": { "AccrualBasis": { "type": "string", "description": "Method used to calculate interest accrual.\n * `BD/252`: Calculates daily interest using a 252-day year and the actual number of business days in each time period.\n * `ACTUAL/360`: Calculates daily interest using a 360-day year and the actual number of days in each time period.\n * `ACTUAL/365`: Calculates daily interest using a 365-day year and the actual number of days in each time period.\n * `ACTUAL/ACTUAL`: Calculates daily interest using the actual number of days in the year (which in the leap year is 366) and the actual number of days in each time period.\n", "enum": [ "BD/252", "ACTUAL/360", "ACTUAL/365", "ACTUAL/ACTUAL" ], "example": "ACTUAL/365" }, "AccrualFrequency": { "type": "string", "description": "Interest accrual frequency", "enum": [ "DAILY", "MONTHLY", "QUARTERLY", "HALF_YEARLY", "YEARLY", "MATURITY" ], "example": "DAILY" }, "Amount": { "type": [ "number", "null" ], "format": "double", "description": "Amount in the `interest_by_tier`", "example": 1000 }, "BenchmarkResponse": { "type": "string", "description": "Market index returned in responses.\n - `BOE`: Bank of England, UK\n - `DI`: Interbank Deposit Contract, Brazil\n - `FED`: Federal Reserve System, USA\n - `FIXED`: Fixed interest rate, no market index\n - `RBA`: Reserve Bank of Australia\n - `RBI`: Reserve Bank of India\n - `TO`: Overnight Interbank Target Rate (Tasa Objetivo), Mexico\n", "enum": [ "BOE", "DI", "FED", "FIXED", "RBA", "RBI", "TO" ], "example": "FIXED" }, "CapEffectiveRate": { "type": "number", "format": "double", "description": "Cap effective rate. If you pass a value for `cap_effective_rate`, you must also pass a value for `cap_threshold`.", "example": 1.2 }, "CapitalizationFrequency": { "type": "string", "description": "Interest payout frequency", "enum": [ "DAILY", "MONTHLY", "QUARTERLY", "HALF_YEARLY", "YEARLY", "MATURITY" ], "example": "DAILY" }, "CapThreshold": { "type": "number", "format": "double", "description": "Cap threshold value. If you pass a value for `cap_threshold`, you must also pass a value for `cap_effective_rate`.", "example": 1.1 }, "CurrentPage": { "type": "integer", "format": "int32", "description": "Current page", "example": 1 }, "CurrencyCode": { "type": "string", "format": "number", "description": "Numeric currency code in ISO 4217 standard. Only the following codes are accepted: 986 (BRL), 826 (GBP), 356 (INR), 840 (USD), 978 (EUR), 604 (PEN), 036 (AUD), 484 (MXN), 764 (THB), 208 (DKK), 752 (SEK), 578 (NOK).", "enum": [ "986", "826", "356", "840", "978", "604", "036", "484", "764", "208", "752", "578" ], "example": "986" }, "Days": { "type": "integer", "format": "int32", "description": "Number of days in `interest_by_tier`", "example": 30 }, "Description": { "type": "string", "description": "Interest plan name", "example": "Banking plan" }, "DivisionId": { "type": "string", "description": "Division ID attached to the interest plan for accrual by division", "example": "d9b2c9e1-4633-4a10-841b-270f7f1493cd" }, "FeeProcessingCode": { "type": "string", "format": "number", "description": "Processing code configured in the [fee model](https://developers.pismo.io/pismo-docs/docs/fee-model) for charging a tax, penalty, or fee.", "example": "001100" }, "WithholdingMoment": { "type": "string", "description": "Moment at which tax is withheld. When omitted, no withholding applies.", "enum": [ "ACCRUAL", "CAPITALIZATION" ], "example": "ACCRUAL" }, "TaxRule": { "type": "object", "description": "A single tax rule applied within a tax withholding configuration.", "required": [ "description", "fixed_percentage" ], "properties": { "description": { "type": "string", "maxLength": 128, "description": "Description of the tax rule.", "example": "IOF" }, "fixed_percentage": { "type": "number", "description": "Fixed percentage applied by the tax rule.", "example": 0.0038 }, "threshold_amount": { "type": [ "number", "null" ], "format": "double", "description": "Optional monetary threshold amount associated with the tax rule. Use null when the rule does not depend on a threshold.", "example": null } } }, "TaxWithholding": { "type": "object", "description": "Tax withholding configuration. Replaces the standalone `fee_processing_code` field.\nConditional rules enforced at creation/update time:\n- `ACCRUAL`: `fee_processing_code` is required; `tax_rules` must be omitted.\n- `CAPITALIZATION`: `tax_rules` is required; `fee_processing_code` must be omitted.\n- Omitted `withholding_moment`: both `fee_processing_code` and `tax_rules` must be omitted.\nIn GET responses, legacy plans that predate this field may return `fee_processing_code` with a null `withholding_moment`.\n", "required": [ "withholding_moment" ], "properties": { "withholding_moment": { "$ref": "#/components/schemas/WithholdingMoment" }, "fee_processing_code": { "$ref": "#/components/schemas/FeeProcessingCode" }, "tax_rules": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/TaxRule" } } } }, "FixedInterestRate": { "type": "number", "format": "float", "description": "Nominal annual interest rate, expressed as a decimal fraction. 0.10 = 10% per year. 1.00 = 100% per year. Do not send 10 for 10%. Maximum precision: 8 decimal places. The platform converts this annual rate to the accrual period using `accrual_basis` and `interest_type`.\n\nIf you pass a value for `benchmark`, this field must be null. Otherwise, it's required.\n", "example": 0.1 }, "FloorEffectiveRate": { "type": "number", "format": "double", "description": "Floor effective rate", "example": 2.2 }, "FloorThreshold": { "type": "number", "format": "double", "description": "Floor threshold value", "example": 2.1 }, "InterestBaseModel": { "type": "string", "description": "Interest calculation model. `CLOSING-BALANCE` calculates interest on a single end-of-day balance snapshot. `BALANCE-CHANGE` calculates interest on each intraday balance movement (for example, credits and debits) as it occurs, so interest accrues on the balance held during each interval between consecutive movements rather than on one end-of-day figure. Defaults to `CLOSING-BALANCE`.", "enum": [ "CLOSING-BALANCE", "BALANCE-CHANGE" ], "default": "CLOSING-BALANCE", "example": "CLOSING-BALANCE" }, "InterestByTiers": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/InterestByTiersType" }, "tier_calculation": { "$ref": "#/components/schemas/TierCalculation" }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/InterestByTiersArrayObject" } } }, "required": [ "type", "tier_calculation", "tiers" ], "description": "Interest by tiers configuration", "example": { "type": "TERM", "tier_calculation": "RETROACTIVE", "tiers": [ { "days": 30, "amount": 1000, "margin_rate": 1, "fixed_interest_rate": 1.2 }, { "days": 60, "amount": 2000, "margin_rate": 1, "fixed_interest_rate": 1.3 } ] } }, "InterestByTiersArrayObject": { "type": "object", "properties": { "days": { "$ref": "#/components/schemas/Days" }, "amount": { "$ref": "#/components/schemas/Amount" }, "margin_rate": { "$ref": "#/components/schemas/MarginRate" }, "fixed_interest_rate": { "$ref": "#/components/schemas/FixedInterestRate" } }, "description": "Tier details for interest calculation" }, "InterestByTiersType": { "type": "string", "description": "Interest type\n- `TERM`: Interest rate varies according to the period of time since the deposit was made.\n- `AMOUNT`: Interest rate varies according to the current balance.\n", "enum": [ "TERM", "AMOUNT" ], "example": "TERM" }, "InterestPlanId": { "type": "string", "format": "UUID", "description": "Interest plan ID generated during the plan's creation. Must be an alphanumeric UUID with the alphabetical characters in lowercase.", "example": "07d84f79-3027-47bd-b628-65528ccc8fb2" }, "InterestPlansResponse": { "type": "object", "properties": { "current_page": { "$ref": "#/components/schemas/CurrentPage" }, "per_page": { "$ref": "#/components/schemas/PerPage" }, "pages": { "$ref": "#/components/schemas/Pages" }, "total_items": { "$ref": "#/components/schemas/TotalItems" }, "items": { "type": "array", "items": { "type": "object", "properties": { "interest_plan_id": { "$ref": "#/components/schemas/InterestPlanId" }, "org_id": { "$ref": "#/components/schemas/OrgId" }, "description": { "$ref": "#/components/schemas/Description" }, "currency_code": { "$ref": "#/components/schemas/CurrencyCode" }, "benchmark": { "$ref": "#/components/schemas/BenchmarkResponse" }, "fixed_interest_rate": { "$ref": "#/components/schemas/FixedInterestRate" }, "margin_rate": { "$ref": "#/components/schemas/MarginRate" }, "margin": { "$ref": "#/components/schemas/Margin" }, "tax_withholding": { "$ref": "#/components/schemas/TaxWithholding" }, "accrual_basis": { "$ref": "#/components/schemas/AccrualBasis" }, "interest_type": { "$ref": "#/components/schemas/InterestType" }, "capitalization_frequency": { "$ref": "#/components/schemas/CapitalizationFrequency" }, "accrual_frequency": { "$ref": "#/components/schemas/AccrualFrequency" }, "status": { "$ref": "#/components/schemas/Status" }, "operation_type": { "$ref": "#/components/schemas/OperationType" }, "start_date": { "$ref": "#/components/schemas/StartDate" }, "interest_by_tiers": { "$ref": "#/components/schemas/InterestByTiers" }, "interest_thresholds": { "$ref": "#/components/schemas/InterestThresholds" }, "division_id": { "$ref": "#/components/schemas/DivisionId" }, "interest_base_model": { "$ref": "#/components/schemas/InterestBaseModel" } } } } } }, "InterestThresholds": { "type": "object", "properties": { "cap_threshold": { "$ref": "#/components/schemas/CapThreshold" }, "cap_effective_rate": { "$ref": "#/components/schemas/CapEffectiveRate" }, "floor_threshold": { "$ref": "#/components/schemas/FloorThreshold" }, "floor_effective_rate": { "$ref": "#/components/schemas/FloorEffectiveRate" } }, "description": "Cap and floor thresholds for the interest plan", "example": { "cap_threshold": 1.1, "cap_effective_rate": 1.2, "floor_threshold": 2.2, "floor_effective_rate": 2.1 } }, "InterestType": { "type": "string", "description": "Interest calculation type\n- `SIMPLE`: Calculated on the original deposit or investment value.\n- `COMPOUND`: Calculated on the original value plus the last accumulated interest.\n", "enum": [ "SIMPLE", "COMPOUND" ], "example": "SIMPLE" }, "Margin": { "type": "number", "format": "double", "description": "Additive spread, in the same unit and period as the benchmark rate: nominal annual, decimal fraction. If `benchmark` is 0.025 and `margin` is 0.0225, the resulting annual rate is 0.0475.\n\nIf you pass a value for `benchmark`, this field is optional. If `benchmark` is null, this field must be null also.\n", "example": 0.02 }, "MarginRate": { "type": [ "number", "null" ], "format": "double", "description": "Multiplier applied to the benchmark rate, expressed as a decimal fraction of 100%. 1.00 = 100% of the benchmark. 1.10 = 110% of the benchmark. 0.95 = 95% of the benchmark. This is not added to the benchmark—use `margin` for an additive spread.\n\nIf you don't pass a value for `benchmark`, this field must be null. Otherwise, it's required.\n", "example": 1.1 }, "OperationType": { "type": "string", "description": "Operation type.\n- `DEBIT`: Interest plan for debit type operations\n- `CREDIT`: Interest plan for credit type operations\n", "enum": [ "DEBIT", "CREDIT" ], "example": "DEBIT" }, "OrgId": { "type": "string", "description": "Organization ID generated in the onboarding process", "example": "TN-cc8f8b89-233a-4582-9f36-63ee85278d6d" }, "Pages": { "type": "integer", "format": "Int32", "description": "Total number of pages. Default is `1`.", "example": 1 }, "PerPage": { "type": "integer", "description": "Number of items per page. Default is `10`.", "format": "Int32", "example": 1 }, "StartDate": { "type": "string", "format": "date", "description": "Date to start applying the benchmark rate in the accrual process. Format = YYYY-MM-DD.", "example": "2024-09-10" }, "Status": { "type": "string", "description": "Interest plan status. Must be set to `ACTIVE`.", "enum": [ "ACTIVE" ], "example": "ACTIVE" }, "TierCalculation": { "type": "string", "description": "Tier calculation method\n- `RETROACTIVE`: Interest is recalculated from the beginning based on the new applicable rate.\n- `NON-RETROACTIVE`: Interest is calculated progressively based on each layer rate.\n", "enum": [ "RETROACTIVE", "NON-RETROACTIVE" ], "example": "RETROACTIVE" }, "TotalItems": { "type": "integer", "format": "int32", "description": "Total number of items", "example": 1 }, "ErrorResponse": { "type": "object", "description": "Standard error payload generated by the global exception handler.\n`message` is a single string for most errors and an array of strings\nwhen multiple bean-validation or request-binding errors occur in the same request.\n", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "example": { "message": "interest account not found" } }, "ErrorResponseDeserialization": { "type": "object", "description": "Error payload generated only when the request body fails JSON deserialization\n(unknown field or invalid JSON structure). Returned with HTTP 400.\n", "additionalProperties": false, "required": [ "error", "status" ], "properties": { "error": { "type": "string", "description": "Short error category." }, "message": { "type": "string", "description": "Details about the field or structure that causes the error." }, "field": { "type": "string", "description": "Name of the invalid field. Present only for unknown-field errors." }, "status": { "type": "integer", "description": "HTTP status code, always 400 for this shape." } }, "example": { "error": "Invalid field in request", "message": "Field 'foo' is not allowed. Only the following fields can be updated: start_date, description, fixed_interest_rate, margin_rate, margin, interest_by_tiers, interest_thresholds", "field": "foo", "status": 400 } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "400BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponseDeserialization" } ] }, "examples": { "validation": { "summary": "Bean validation or binding errors", "value": { "message": [ "fixed_interest_rate must be informed", "margin_rate must be positive" ] } }, "requestBody": { "summary": "invalid or missing request value", "value": { "message": "Failed to process your request. Validate the fields in your request." } }, "tenantHeader": { "summary": "Tenant header missing or malformed", "value": { "message": "x-tenant header is missing or malformed" } }, "unknownField": { "summary": "Unknown field in request body", "value": { "error": "Invalid field in request", "message": "Field 'foo' is not allowed. Only the following fields can be updated: start_date, description, fixed_interest_rate, margin_rate, margin, interest_by_tiers, interest_thresholds", "field": "foo", "status": 400 } }, "invalidJson": { "summary": "Invalid JSON body", "value": { "error": "Invalid JSON format", "message": "Request contains invalid JSON structure or field types", "status": 400 } }, "taxWithholdingAccrualFeeRequired": { "summary": "ACCRUAL withholding without fee_processing_code", "value": { "message": [ "fee_processing_code is required when tax_withholding.withholding_moment is ACCRUAL." ] } }, "taxWithholdingAccrualTaxRulesNotAllowed": { "summary": "ACCRUAL withholding with tax_rules present", "value": { "message": [ "tax_rules must be null when tax_withholding.withholding_moment is ACCRUAL." ] } }, "taxWithholdingCapitalizationFeeNotAllowed": { "summary": "CAPITALIZATION withholding with fee_processing_code present", "value": { "message": [ "fee_processing_code must be null when tax_withholding.withholding_moment is CAPITALIZATION." ] } }, "taxWithholdingCapitalizationTaxRulesRequired": { "summary": "CAPITALIZATION withholding without tax_rules", "value": { "message": [ "tax_rules is required when tax_withholding.withholding_moment is CAPITALIZATION." ] } }, "taxWithholdingNoneFieldsNotAllowed": { "summary": "NULL withholding_moment with fee_processing_code or tax_rules present", "value": { "message": [ "fee_processing_code and tax_rules must be null when tax_withholding.withholding_moment is NULL." ] } }, "taxWithholdingNotAllowedWhenTaxesExemption": { "summary": "taxes_exemption is true with tax_withholding present", "value": { "message": [ "tax_withholding must be null when taxes_exemption is true." ] } } } } } }, "401Unauthorized": { "description": "Unauthorized. The response body is produced by the upstream authentication gateway and is not defined by this service." }, "404NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "interestAccountNotFound": { "summary": "Interest account not found", "value": { "message": "interest account not found" } }, "interestPlanNotFound": { "summary": "Interest plan not found", "value": { "message": "interest plan not found" } }, "benchmarkNotFound": { "summary": "Benchmark not found", "value": { "message": "benchmark not found" } } } } } }, "500InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Failed to process your request" } } } } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/v1/interest/plan": { "get": { "summary": "List Org interest plans", "description": "List all interest plans for a given Org.", "tags": [ "Interest engine" ], "operationId": "get-v1-interest-plans", "parameters": [ { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterestPlansResponse" } } } }, "400": { "$ref": "#/components/responses/400BadRequest" }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "404": { "$ref": "#/components/responses/404NotFound" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } } } } ```