APIs
Sub-processorsAbout PismoContact us

Update account interest

put
https://sandbox.pismolabs.io/interest-engine/v1/interest/account/

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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
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.

Body Params

Full interest configuration for the account. See the schema description for the conditional required-field rules in benchmark, fixed_interest_rate, margin_rate, margin, tax_withholding, and taxes_exemption.

Request body for PUT /v1/interest/account/{accountId}. The endpoint replaces the full interest configuration of the account, partial updates are not supported. Every request must redeclare a complete configuration that satisfies the rules below.

Interest type. Exactly one of the two paths must be chosen:

  • Benchmark-indexed rate: If you pass benchmark and margin_rate., then margin is optional. fixed_interest_rate must be omitted.
  • Fixed rate: If you pass fixed_interest_rate, then benchmark, margin_rate, and margin must all be omitted.

Passing neither benchmark nor fixed_interest_rate returns 400 Bad Request with fixed_interest_rate must be provided. Passing both returns 400 Bad Request with fixed_interest_rate is not allowed when benchmark is passed.

Tax-withholding rule: Driven by tax_withholding.withholding_moment:

  • When withholding_moment is ACCRUAL, fee_processing_code is required and tax_rules must be omitted.
  • When withholding_moment is CAPITALIZATION, tax_rules is required and fee_processing_code must be omitted.
  • When tax_withholding is omitted, no withholding is configured.

Tax-exemption rule: When taxes_exemption is true, tax_withholding must be null. When taxes_exemption is false or omitted, tax_withholding follows the rule above.

Numeric fields (fixed_interest_rate, margin_rate) must have a positive value. tax_withholding.fee_processing_code is limited to 128 characters.

string
enum

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
Allowed:
float

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.

double | null

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.

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.

boolean

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

tax_withholding
object

Tax withholding configuration. Replaces the standalone fee_processing_code field. Conditional rules enforced at creation/update time:

  • ACCRUAL: fee_processing_code is required; tax_rules must be omitted.
  • CAPITALIZATION: tax_rules is required; fee_processing_code must be omitted.
  • Omitted withholding_moment: both fee_processing_code and tax_rules must be omitted. In GET responses, legacy plans that predate this field may return fee_processing_code with a null withholding_moment.
interest_by_tiers
object

Interest by tiers configuration

string
enum

Optional account-level capitalization frequency. When provided with a valid value, it overrides the capitalization frequency configured in the associated interest plan. If omitted or sent as null, the current account-level value remains unchanged. If there is no existing account-level value, then the associated interest plan value is used during processing.

Allowed:
Responses

401

Unauthorized. The response body is produced by the upstream authentication gateway and is not defined by this service.

Updated 4 months ago

Did this page help you?
Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 4 months ago

Did this page help you?