PIpismo
Account attachment

Update deposit account attachment overrides

Partially updates deposit_configs.maturity_period, deposit_configs.overrides and deposit_configs.interest_capitalization_mode on an active deposit account attachment. The overrides fields are processed using three‑state PATCH semantics, allowing values to be added, changed, or cleared as part of the update.

  • Omitted: Keeps the current value
  • null: Removes the override; falls back through the cascade (program → product)
  • Value: Replaces the current override with the supplied value

NOTES:

  • At least one of deposit_configs.maturity_period, deposit_configs.overrides or deposit_configs.interest_capitalization_mode must be provided. A payload carrying only maturity_period is valid.
  • The overrides envelope, if provided, must contain at least one field. Sending an empty object returns 400 EIBACC0315.
  • renewal_term still requires ROLLOVER configured in maturity_instructions somewhere in the fallback sequence (400 EIBACC0310 otherwise).
  • maturity_period changes the term in force and takes effect immediately, recalculating the current cycle's maturity date from the attachment's effective_date. It's accepted in both documented forms (unit+value or calendar_maturity_date) and doesn't follow the three-state semantics above: null is a no-op, not a removal.
  • maturity_period and overrides.renewal_term are independent. renewal_term keeps applying at rollover only and never recalculates the current cycle's maturity date.
  • When maturity_period changes, the schedules driven by the maturity date (maturity instruction, maturity notices) are re-evaluated against the new date.
  • product_id and payout_account stay fixed after attach and are ignored if included in the request body. To change the payout account, use Update payout account for deposit account.

This endpoint generates an Account attachment updated event that includes the active term in data.maturity_period. If the account has an external account ID, the event also includes it in data.external_account_id.

The response returns external_account_id whenever the account has one; it is omitted for an account with no external identifier.

patch/v1/deposits/accounts/{accountId}/attachment

Request

  • Base URL
    https://sandbox.pismolabs.io/savings-products
  • URL
    https://sandbox.pismolabs.io/savings-products/v1/deposits/accounts/{accountId}/attachment
  • Auth
    HTTP bearer

Path parameters

accountIdstring required

Account ID. Accepts either the Pismo account_id or your external_account_id. Send the same ID used to generate the access token.

Request body

Example request

{
  "deposit_configs": {
    "maturity_period": {
      "unit": "MONTHS",
      "value": 6,
      "calendar_maturity_date": "2027-06-15"
    },
    "interest_capitalization_mode": "REINVEST",
    "overrides": {
      "maturity_instructions": {
        "principal": "ROLLOVER",
        "interest": "PAY",
        "reason": "Customer preference at onboarding"
      },
      "renewal_term": {
        "unit": "MONTHS",
        "value": 6,
        "renewal_calendar_maturity_date": "2027-05-22"
      },
      "penalties": {
        "reason": "Update — Q1 2027 VIP retention package",
        "withdrawal_fee": {
          "value": 1.5
        }
      }
    }
  }
}

Response

OK

product_type'deposit' | 'savings-account'

Product type.

product_idstring

Product identifier.

external_account_idstring

External account ID. Returned only when the account has an external account identifier.

interest_plan_idstring

Interest rate plan ID. This corresponds to the ID you created using the Create interest plan version) endpoint.

attachment_datestring date-time

Timestamp that indicates when the attachment was created (when the attach API call was made). The datetime format follows the ISO 8601 standard yyyy-mm-ddThh:mm:ss.sssZ.

effective_datestring date

The effective date of the attachment in YYYY-MM-DD format This is the date when the attachment becomes valid. Maturity is calculated from this date. For attachments created in the past, the date defaults to the value of attachment_date.

fee_model_idstring

Fee model identifier, if applicable.

interest_capitalization_mode'PAYOUT' | 'REINVEST'

Present only when this account attachment explicitly defines interest_capitalization_mode. If the field is missing, the effective value is REINVEST, inherited from the program configuration or, if the program does not specify it, from the product’s default settings.

accrual_model'DEPOSIT_BASIS' | 'BALANCE_BASIS'

Accrual model inherited from the attached product. DEPOSIT_BASIS or BALANCE_BASIS.

balance_type'VALUE_DATED_BALANCE' | 'LEDGER_BALANCE'

Balance type inherited from the attached product. Only meaningful when accrual_model is BALANCE_BASIS.

Example response

{
  "product_id": "2c336e9d-d04f-4fd0-8f6e-25808f48d70c",
  "external_account_id": "ext-acct-001",
  "interest_plan_id": "263d509a-d5d0-4b3a-b909-ce1b9174beff",
  "maturity_period": {
    "unit": "MONTHS",
    "value": 6,
    "calendar_maturity_date": "2027-06-15"
  },
  "attachment_date": "2024-01-23T13:26:25.000Z",
  "effective_date": "2025-12-01",
  "fee_model_id": "fee-model-123",
  "payout_account": {
    "label": "My payout account",
    "type": "INTERNAL",
    "internal_account_id": 123456,
    "external_account": {
      "key": "value"
    }
  },
  "interest_capitalization_mode": "REINVEST",
  "overrides": {
    "maturity_instructions": {
      "principal": "ROLLOVER",
      "interest": "PAY",
      "reason": "Customer preference at onboarding"
    },
    "renewal_term": {
      "unit": "MONTHS",
      "value": 6,
      "renewal_calendar_maturity_date": "2027-05-22"
    },
    "penalties": {
      "reason": "Q4 2026 VIP retention package",
      "withdrawal_fee": {
        "value": 1.5
      }
    }
  },
  "accrual_model": "DEPOSIT_BASIS",
  "balance_type": "VALUE_DATED_BALANCE"
}

Changes

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