PIpismo
Account interest

Update account interest

Apply specific interest accrual options to an account by replacing its full interest configuration.

This operation has full-replacement semantics: every request must redeclare the complete configuration. Partial updates (sending only the fields you want to change) are not supported and cause the validation to fail.

Although every property in the request body is independently optional, the body as a whole must satisfy several conditional rules. See the request body schema description for the full set of benchmark/fixed_interest_rate, tax_withholding, and taxes_exemption rules.

Account identification. The token identifies the account. Exactly one of x-account-id or x-external-account-id must be passed and must match the {accountId} path parameter. Otherwise the request is rejected (403 on a mismatch or when neither header is passed, 400 when both are).

Stored identifiers. Which identifiers are stored follows the header used:

  • x-account-id: An Accounts API call confirms the account ID exists, then account_id is stored and external_account_id is stored as null - any external account ID previously stored for this account is cleared.
  • x-external-account-id: A Corporate API call resolves the external account ID to a Pismo account_id, and both IDs are stored.

If the Accounts or Corporate API cannot resolve the identifier the request fails with 400 and nothing is persisted. Any other failure of those APIs fails with 500. In both cases, the interest account is left unchanged and no update event is emitted.

put/v1/interest/account/{accountId}

Request

  • Base URL
    https://sandbox.pismolabs.io/interest-engine
  • URL
    https://sandbox.pismolabs.io/interest-engine/v1/interest/account/{accountId}
  • Auth
    HTTP bearer

Path parameters

accountIdstring required

Account ID. Must match the account encoded in the account token. This can be a Pismo account ID or an external account ID. A mismatch is rejected with 403 Forbidden. Maximum 60 characters.

Request body

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

Market index used to measure interest value over time. For fixed interest, this field must be null.

  • BOE: Bank of England, UK
  • DI: Interbank Deposit Contract, Brazil
  • FED: Federal Reserve System, USA
  • 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.

taxes_exemptionboolean

When true, the account is exempt from tax withholding and tax_withholding must be null.

capitalization_frequency'DAILY' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY' | 'MATURITY'

Interest payout frequency

Example request

{
  "benchmark": "FED",
  "margin_rate": 1.3,
  "margin": 0.05,
  "tax_withholding": {
    "withholding_moment": "ACCRUAL",
    "fee_processing_code": "001100"
  }
}

Response

OK

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.

taxes_exemptionboolean

Is the account exempt from taxes?

capitalization_frequency'DAILY' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY' | 'MATURITY'

Interest payout frequency

external_account_idstring

External account ID, at most 60 characters, provided by the client system that owns the account. It cannot be passed directly in a request body—it's parsed from an external account ID token, and it's included in responses and events for accounts that have it stored.

account_idstring

Pismo account ID. Returned only when the request was authenticated with a Pismo account ID token. Omitted otherwise.

Example response

{
  "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
      }
    ]
  },
  "taxes_exemption": true,
  "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
      }
    ]
  },
  "capitalization_frequency": "DAILY",
  "external_account_id": "account-xyz-987",
  "account_id": "8080"
}

Changes

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