APIs
Sub-processorsAbout PismoContact us

Partially update account interest [Beta]

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

Record an effective-dated change to the interest configuration of an account. Send only the interest parameters you want to change, together with the date on which the change takes effect. The change is appended to the account's history of configuration changes, which you can retrieve with Get account interest.

Key features:

  • Updates only the provided parameters. A parameter that is omitted is left untouched, and a parameter sent as null clears the account-level value so the interest plan value applies.
  • Applies from effective_date and, optionally, up to end_date. After end_date, the configuration that applied before the change takes effect again.
  • Allows overlapping changes. For each parameter, the most recently created change that covers a date determines the value that applies on that date.
  • Validates the resulting configuration for every date from today onward and rejects the request with 400 when it is invalid.
  • Rejects requests that contain no interest parameter, only dates and metadata.

Once an account has a configuration change, PUT /v1/interest/account/{accountId} is rejected for that account with 409.

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 with the change.
  • x-external-account-id: A Corporate API call resolves the external account ID to a Pismo account_id, and both IDs are stored with the change.

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.

Idempotency. If a change was already recorded with the same x-cid for the organization, the request succeeds without recording a second change.

When a new change is recorded, the endpoint publishes an interest_account_update_success event.

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

Interest parameters to change and the dates on which the change applies. Refer to the schema description for the rules applied to the resulting configuration.

Request body for PATCH /v1/interest/account/{accountId}. The endpoint records an
effective-dated change to the interest configuration of the account. Changes are appended
to the account's history, and earlier changes are never modified or deleted.

Send only the interest parameters you want to change. At least one is required:

  • A parameter that is omitted is left untouched by this change.
  • A parameter sent as null clears the account-level value, so the value from the
    associated interest plan applies.
  • tax_withholding and interest_by_tiers are replaced as a whole. Their fields are not
    merged with the values of earlier changes.

effective_date is required. A request that contains only effective_date, end_date,
and metadata, or an empty tax_withholding object, is rejected with 400 Bad Request.

Changes can overlap. For each interest parameter, the most recently created change that
covers a given date determines the value that applies on that date.

The configuration that results from the change is validated for every date from today
onward, using the same rules as PUT /v1/interest/account/{accountId}:

  • Interest type: With benchmark and margin_rate, margin is optional and
    fixed_interest_rate must be omitted. With fixed_interest_rate, benchmark,
    margin_rate, and margin must be omitted. When fixed_interest_rate is sent without
    benchmark, the change is stored with benchmark set to FIXED.
  • Tax withholding: With withholding_moment set to ACCRUAL, fee_processing_code is
    required and tax_rules must be omitted. With CAPITALIZATION, tax_rules is required
    and fee_processing_code must be omitted.
  • Tax exemption: When taxes_exemption is true, tax_withholding must be null.

fixed_interest_rate, margin_rate, and margin must be positive, and are stored and
returned with 8 decimal places.

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

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.

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.

Is the account exempt from taxes?

tax_withholding
interest_by_tiers
enum

Account-level capitalization frequency. When null, the capitalization frequency of the associated interest plan applies.

Interest payout frequency

date
required

First day on which the change applies. Format = YYYY-MM-DD.

date | null

Last day on which the change applies, inclusive. After this day, the configuration that applied before the change takes effect again. When omitted or null, the change has no end date. Must be equal to or greater than effective_date. Format = YYYY-MM-DD.

metadata
object

Free-form key-value data to store with the change. The serialized JSON can be at most 4096 bytes. When omitted, an empty object is stored and returned.

Responses

401

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

Updated about 16 hours 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 about 16 hours ago

Did this page help you?