Interest engine

Get interest plan

Get interest plan details. By default, returns the latest version of the interest plan. You can optionally specify a version_date query parameter to retrieve the version that was active on a specific date. If a version_date is provided, the endpoint returns the latest version with a start date less than or equal to the specified date.

get/v1/interest/plan/{interestPlanId}

Request

Base URL
https://sandbox.pismolabs.io/interest-engine
URL
https://sandbox.pismolabs.io/interest-engine/v1/interest/plan/{interestPlanId}
Auth
HTTP bearer

Path parameters

interestPlanIdstring required

Interest plan ID generated during the plan's creation. Must be an alphanumeric UUID with the alphabetical characters in lowercase.

Query parameters

version_datestring date

Optional date to retrieve a specific version of the interest plan. If not provided, returns the latest version. Format = YYYY-MM-DD.

Response

interest_plan_idstring uuid

Interest plan ID generated during the plan's creation. Must be an alphanumeric UUID with the alphabetical characters in lowercase.

org_idstring

Organization ID generated in the onboarding process

descriptionstring

Interest plan name

currency_code'986' | '826' | '356' | '840' | '978' | '604' | '036' | '484' | '764' | '208' | '752' | '578'

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).

benchmark'BOE' | 'DI' | 'FED' | 'FIXED' | 'RBA' | 'RBI' | 'TO'

Market index returned in responses.

BOE: Bank of England, UK
DI: Interbank Deposit Contract, Brazil
FED: Federal Reserve System, USA
FIXED: Fixed interest rate, no market index
RBA: Reserve Bank of Australia
RBI: Reserve Bank of India
TO: Overnight Interbank Target Rate (Tasa Objetivo), Mexico

fixed_interest_ratenumber float nullable

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.

If you pass a value for benchmark, this field must be null. Otherwise, it's required.

margin_ratenumber double nullable

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.

If you don't pass a value for benchmark, this field must be null. Otherwise, it's required.

marginnumber double

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.

If you pass a value for benchmark, this field is optional. If benchmark is null, this field must be null also.

accrual_basis'BD/252' | 'ACTUAL/360' | 'ACTUAL/365' | 'ACTUAL/ACTUAL'

Method used to calculate interest accrual.

BD/252: Calculates daily interest using a 252-day year and the actual number of business days in each time period.
ACTUAL/360: Calculates daily interest using a 360-day year and the actual number of days in each time period.
ACTUAL/365: Calculates daily interest using a 365-day year and the actual number of days in each time period.
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.

interest_type'SIMPLE' | 'COMPOUND'

Interest calculation type

SIMPLE: Calculated on the original deposit or investment value.
COMPOUND: Calculated on the original value plus the last accumulated interest.

operation_type'DEBIT' | 'CREDIT'

Operation type.

DEBIT: Interest plan for debit type operations
CREDIT: Interest plan for credit type operations

status'ACTIVE'

Interest plan status. Must be set to ACTIVE.

start_datestring date

Date to start applying the interest plan. Format = YYYY-MM-DD.

Interest payout frequency

Interest accrual frequency

interest_base_model'CLOSING-BALANCE' | 'BALANCE-CHANGE'

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.

Example response

{
  "interest_plan_id": "07d84f79-3027-47bd-b628-65528ccc8fb2",
  "org_id": "TN-cc8f8b89-233a-4582-9f36-63ee85278d6d",
  "description": "Banking plan",
  "currency_code": "986",
  "benchmark": "FIXED",
  "fixed_interest_rate": 0.1,
  "margin_rate": 1.1,
  "margin": 0.02,
  "tax_withholding": {
    "withholding_moment": "ACCRUAL",
    "fee_processing_code": "001100",
    "tax_rules": [
      {
        "description": "IOF",
        "fixed_percentage": 0.0038
      }
    ]
  },
  "accrual_basis": "ACTUAL/365",
  "interest_type": "SIMPLE",
  "operation_type": "DEBIT",
  "status": "ACTIVE",
  "start_date": "2025-06-17",
  "capitalization_frequency": "DAILY",
  "accrual_frequency": "DAILY",
  "interest_by_tiers": {
    "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
      }
    ]
  },
  "interest_thresholds": {
    "cap_threshold": 1.1,
    "cap_effective_rate": 1.2,
    "floor_threshold": 2.2,
    "floor_effective_rate": 2.1
  },
  "interest_base_model": "CLOSING-BALANCE"
}

Changes

No recorded changes to this operation across all 1 revision of this API.