1 of 6

Deposit contract management

In this block, you will find the most common use cases that explain how to manage an active deposit contract.

Below you will find the following sections:

Change payout details

Use case

payoutDetails Parameter

The payoutDetails parameter is optional and can only be defined for an active deposit contract.

Supported Account Types

Payout details support the following account number types:

Click on the tabs below to see the formatting for each account number types.

Default Behavior

If payout details are not specified for a contract version, the payout will automatically be directed to the servicing account. It is not necessary to define the servicing account as the payout account in this case.

Modifying Payout Details

Payout details can be modified or removed. To remove payout details from an active contract version, include the following in the request:

Sample API call

To change the deposit contract payout details, make the following API call.

Sample response

Below you find an example response body to the API call above.

Response

Result

As a result, the deposit contract payout details were updated.

Change contract prolongation status

Use case

Prolongation types

The prolongationCode parameter can have one of the following values:

PRINCIPAL - The deposit contract is extended to a new period with only the initial deposit principal amount. All interest accrued during the term will be paid out to the payout account defined for the deposit.
PRINCIPAL_WITH_INTEREST - The deposit contract is extended to a new period with both the initial deposit principal amount and the interest accrued during the previous term. The interest is capitalised, meaning it is added to the initial principal amount, resulting in a new principal amount for the next term period.

Sample API call

To change the deposit contract prolongation details, make the following API call.

Sample request

Below is an example request body of the API call for changing deposit contract payout details.

Sample response

Below you find an example response body to the API call above.

Response

Result

As a result, the deposit contract prolongation status was updated.

Update contract header

Use case

In this example, we will review how to modify the tax exemption status and tax residency country assigned to an active deposit contract. These values are stored on the contract header level. After updating the contract header, these parameters will apply to all versions of the deposit contract.

Use case data

API parameters

...v2/contracts/ID-1696407222

We will change the tax residency country from Estonia to Germany.

We will set the tax exemption to true.

Sample API call

Sample request

Below is an example request body of the API call for changing deposit contract payout details.

{
  "taxResidencyCountryCode": "DE",
  "taxExempt": "true"
}

curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v2/contracts/ID-1696407222' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMjFUMTQ6NDg6MTciLCJleHAiOjE3Mjk1MjIwOTcsInJvbGVzIjpbIkFETUlOIl19.pM0GzsEXo-IsdVy5X2l9FcORAul0_XaH_SEU_HNugjI' \
--header 'Content-Type: application/json' \
--data '{
  "taxResidencyCountryCode": "DE",
  "taxExempt": "true"
}'

Sample response

Below you find an example response body to the API call above.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "headerId": "ID-1696407222",
        "personId": "ID-2660",
        "accountId": "ID-1012",
        "applicationId": "ID-1696407202",
        "offerId": "ID-1718024054",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "contractNumber": "PR-EE-1001",
        "countryCode": "EE",
        "channelCode": "BACKOFFICE",
        "tenantCode": "MB",
        "depositClassCode": "PREMIUM_CUSTOMER",
        "headerActivationDate": "2026-07-08",
        "headerClosingDate": null,
        "activeVersion": {
            "versionId": "ID-1718024033",
            "headerId": "ID-1718024017",
            "versionNumber": 1,
            "statusCode": "ACTIVE",
            "preparationDate": "2026-07-08",
            "signingDate": null,
            "activationDate": "2026-07-08",
            "endDate": "2026-10-08",
            "closingDate": null,
            "period": 3,
            "periodTypeCode": "MONTH",
            "interestRate": 0.25,
            "interestPaymentFrequencyCode": "MONTH",
            "prolongCode": null,
            "countryCode": "EE",
            "cancelReasonCode": null,
            "lastCreditReceiveDate": "2026-07-10",
            "lastSigningDate": null,
            "changeTypeCode": "NEW_CONTRACT",
            "components": [
                {
                    "componentId": "ID-1718024154",
                    "versionId": "ID-1718024033",
                    "componentTypeCode": "PRI",
                    "initialMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": null,
                    "rateBaseCode": null,
                    "rate": null,
                    "accruedUntil": null,
                    "paymentDay": 8,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": null
                },
                {
                    "componentId": "ID-1718024155",
                    "versionId": "ID-1718024033",
                    "componentTypeCode": "INT",
                    "initialMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": {
                        "daysInMonth": "30",
                        "daysInYear": 360
                    },
                    "rateBaseCode": null,
                    "rate": 0.25,
                    "accruedUntil": null,
                    "paymentDay": 8,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": "2026-07-08"
                }
            ],
            "totalInterestMoney": {
                "amount": 3.13,
                "currencyCode": "EUR"
            },
            "totalInterestAccruedMoney": {
                "amount": 0.00,
                "currencyCode": "EUR"
            },
            "channelCode": "BACKOFFICE",
            "tenantCode": "MB",
            "terminationType": "WITHOUT_INTEREST",
            "nextPayoutDate": "2026-08-08",
            "payoutDetails": {
                "name": "Tech",
                "accountNumber": {
                    "value": "EE201225862567235311",
                    "type": "IBAN"
                },
                "financialInstitutionId": null,
                "referenceNumber": null,
                "countryCode": null
            }
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "DE",
        "taxExempt": true,
        "rateBaseCode": null
    }
}

Result

As a result, the tax residency country was updated and the tax exemption was set to true. The updated settings were applied to all existing deposit contract versions.

Adjust deposit contract interest

Use case

Use case data

API parameters with values

The contract header is ID-1696407222. See find deposit contract page for more details.

...contracts/ID-1696407222/adjustments

The contract adjustment is an interest increase. And the component is interest. Note: to create an interest decrease adjustment, use the following value for the eventTypeCode parameter: INTEREST_DECREASE.

The interest increase amount is 0.25 EUR. Note: the contract interest adjustments must fall within the overall deposit interest adjustments rule.

Sample API call

Sample request

Below is an example request body of the API call for changing deposit contract payout details.

{
  "valueDateRule": "APPROVAL_DATE",
  "valueDate": "2027-03-06",
  "eventTypeCode": "INTEREST_INCREASE",
  "details": "Test",
  "componentTypeCode": "INT",
  "money": {
    "amount": 0.25,
    "currencyCode": "EUR"
  }
}

curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v1/contracts/ID-1696407222/adjustments' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDMtMTVUMTU6Mjk6MzgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE3MTA1MTY1Nzh9.B5YRuidueo8Ykoqv3z89Jm1rYSwPe2_B1w7Kk_sjP-k' \
--header 'Content-Type: application/json' \
--data '{
  "valueDateRule": "APPROVAL_DATE",
  "valueDate": "2027-03-06",
  "eventTypeCode": "INTEREST_INCREASE",
  "details": "Test",
  "componentTypeCode": "INT",
  "money": {
    "amount": 0.25,
    "currencyCode": "EUR"
  }
}'

Sample response

Below you will find an example response body to the API call above.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "adjustmentBookingId": "ID-1021",
        "componentTypeCode": "INT",
        "eventTypeCode": "INTEREST_INCREASE",
        "adjustmentType": "BOOKING",
        "postingDate": "2027-06-03",
        "valueDateRule": "APPROVAL_DATE",
        "valueDate": "2027-06-03",
        "statusCode": "PROCESSED",
        "initiatedByUserId": "1",
        "amountMoney": {
            "amount": 0.25,
            "currencyCode": "EUR"
        },
        "details": "Test",
        "source": {
            "sourceName": "DEPOSIT.CONTRACT_HEADER",
            "sourceRef": "ID-1696407222",
            "sourceLink": null
        },
        "originalAdjustmentBookingId": null,
        "headerId": "ID-1696407222",
        "personId": "ID-2660",
        "versionId": "ID-1696407267"
    }
}

Result

As a result a deposit contract interest adjustment: INTEREST_INCREASE with ID-1021 was created.

Make premature termination

Use case

Use case data

API parameters with values

...contracts/ID-1696407222/...

.../versions/ID-1696407267/...

The deposit contract is terminated without any of the interest it has accrued during the term period.

Sample API call

To terminate an active contract prematurely, make the following API call.

Sample request

Below is an example request body of the API call for changing deposit contract payout details.

{
  "terminationType": "WITHOUT_INTEREST",
  "comment": "Closing contract"
}

curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v1/contracts/ID-1696407222/versions/ID-1696407267/prepare-for-termination' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDMtMTVUMTg6MzM6MzYiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE3MTA1Mjc2MTZ9.v5803cMEIrcXdTAnbWPEzODtlb0_YKspKRosMtjNyRg' \
--header 'Content-Type: application/json' \
--data '{
  "terminationType": "WITHOUT_INTEREST",
  "comment": "Closing contract"
}'

Sample response

Below you will find an example response body to the API call above

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "headerId": "ID-1696407222",
        "personId": "ID-2660",
        "accountId": "ID-1012",
        "applicationId": null,
        "offerId": "ID-1718024051",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "contractNumber": "PR-EE-1000",
        "countryCode": "EE",
        "channelCode": "BACKOFFICE",
        "tenantCode": "MB",
        "depositClassCode": "PREMIUM_CUSTOMER",
        "headerActivationDate": "2026-04-04",
        "headerClosingDate": null,
        "activeVersion": {
            "versionId": "ID-1696407267",
            "headerId": "ID-1696407222",
            "versionNumber": 1,
            "statusCode": "TERMINATING",
            "preparationDate": "2026-04-04",
            "signingDate": null,
            "activationDate": "2026-04-04",
            "endDate": "2026-07-04",
            "closingDate": null,
            "period": 3,
            "periodTypeCode": "MONTH",
            "interestRate": 0.25,
            "interestPaymentFrequencyCode": "MONTH",
            "prolongCode": "PRINCIPAL",
            "countryCode": "EE",
            "cancelReasonCode": null,
            "lastCreditReceiveDate": "2026-04-06",
            "lastSigningDate": null,
            "changeTypeCode": "NEW_CONTRACT",
            "components": [
                {
                    "componentId": "ID-1718024140",
                    "versionId": "ID-1718024026",
                    "componentTypeCode": "PRI",
                    "initialMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 4995.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": null,
                    "rateBaseCode": null,
                    "rate": null,
                    "accruedUntil": null,
                    "paymentDay": 4,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": null
                },
                {
                    "componentId": "ID-1718024141",
                    "versionId": "ID-1718024026",
                    "componentTypeCode": "INT",
                    "initialMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": {
                        "daysInMonth": "30",
                        "daysInYear": 360
                    },
                    "rateBaseCode": null,
                    "rate": 0.25,
                    "accruedUntil": "2026-06-04",
                    "paymentDay": 4,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": "2026-06-04"
                }
            ],
            "totalInterestMoney": {
                "amount": 3.13,
                "currencyCode": "EUR"
            },
            "totalInterestAccruedMoney": {
                "amount": 0.25,
                "currencyCode": "EUR"
            },
            "channelCode": "BACKOFFICE",
            "tenantCode": "MB",
            "terminationType": "WITHOUT_INTEREST",
            "nextPayoutDate": "2026-07-04",
            "payoutDetails": {
                "name": "Test Account",
                "accountNumber": {
                    "value": "EE111236525217358748",
                    "type": "IBAN"
                },
                "financialInstitutionId": null,
                "referenceNumber": null,
                "countryCode": null
            }
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false,
        "rateBaseCode": null
    }
}

Result

As a result, the deposit contract is set to the TERMINATING status.

Once the Tuum system completes the internal verification process, the contract will automatically be set to the TERMINATED status. The payout of the principal, or principal with interest, will be made to the servicing or payout account.

Make premature termination

Use case

In this example, we will review how to terminate an active contract prematurely (before the contract reaches its end date). We will use the that was previously created.

Use case data

API parameters with values

The contract header is ID-1696407222. See the page for more details.

...contracts/ID-1696407222/...

The active contract version is ID-1696407267. See the page for more details.

.../versions/ID-1696407267/...

The deposit contract is terminated without any of the interest it has accrued during the term period.

"terminationType": "WITHOUT_INTEREST"

Sample API call

To terminate an active contract prematurely, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v2/contracts/{headerId}/versions/{versionId}/prepare-for-termination

See more information about the endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for changing deposit contract payout details.

{
  "terminationType": "WITHOUT_INTEREST",
  "comment": "Closing contract"
}

curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v1/contracts/ID-1696407222/versions/ID-1696407267/prepare-for-termination' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDMtMTVUMTg6MzM6MzYiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE3MTA1Mjc2MTZ9.v5803cMEIrcXdTAnbWPEzODtlb0_YKspKRosMtjNyRg' \
--header 'Content-Type: application/json' \
--data '{
  "terminationType": "WITHOUT_INTEREST",
  "comment": "Closing contract"
}'

Sample response

Below you will find an example response body to the API call above

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "headerId": "ID-1696407222",
        "personId": "ID-2660",
        "accountId": "ID-1012",
        "applicationId": null,
        "offerId": "ID-1718024051",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "contractNumber": "PR-EE-1000",
        "countryCode": "EE",
        "channelCode": "BACKOFFICE",
        "tenantCode": "MB",
        "depositClassCode": "PREMIUM_CUSTOMER",
        "headerActivationDate": "2026-04-04",
        "headerClosingDate": null,
        "activeVersion": {
            "versionId": "ID-1696407267",
            "headerId": "ID-1696407222",
            "versionNumber": 1,
            "statusCode": "TERMINATING",
            "preparationDate": "2026-04-04",
            "signingDate": null,
            "activationDate": "2026-04-04",
            "endDate": "2026-07-04",
            "closingDate": null,
            "period": 3,
            "periodTypeCode": "MONTH",
            "interestRate": 0.25,
            "interestPaymentFrequencyCode": "MONTH",
            "prolongCode": "PRINCIPAL",
            "countryCode": "EE",
            "cancelReasonCode": null,
            "lastCreditReceiveDate": "2026-04-06",
            "lastSigningDate": null,
            "changeTypeCode": "NEW_CONTRACT",
            "components": [
                {
                    "componentId": "ID-1718024140",
                    "versionId": "ID-1718024026",
                    "componentTypeCode": "PRI",
                    "initialMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 4995.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": null,
                    "rateBaseCode": null,
                    "rate": null,
                    "accruedUntil": null,
                    "paymentDay": 4,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": null
                },
                {
                    "componentId": "ID-1718024141",
                    "versionId": "ID-1718024026",
                    "componentTypeCode": "INT",
                    "initialMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": {
                        "daysInMonth": "30",
                        "daysInYear": 360
                    },
                    "rateBaseCode": null,
                    "rate": 0.25,
                    "accruedUntil": "2026-06-04",
                    "paymentDay": 4,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": "2026-06-04"
                }
            ],
            "totalInterestMoney": {
                "amount": 3.13,
                "currencyCode": "EUR"
            },
            "totalInterestAccruedMoney": {
                "amount": 0.25,
                "currencyCode": "EUR"
            },
            "channelCode": "BACKOFFICE",
            "tenantCode": "MB",
            "terminationType": "WITHOUT_INTEREST",
            "nextPayoutDate": "2026-07-04",
            "payoutDetails": {
                "name": "Test Account",
                "accountNumber": {
                    "value": "EE111236525217358748",
                    "type": "IBAN"
                },
                "financialInstitutionId": null,
                "referenceNumber": null,
                "countryCode": null
            }
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false,
        "rateBaseCode": null
    }
}

Result

As a result, the deposit contract is set to the TERMINATING status.

Update contract header

Use case

Use case data

API parameters

The contract header is ID-1696407222. See the page for more details.

...v2/contracts/ID-1696407222

We will change the tax residency country from Estonia to Germany.

"taxResidencyCountryCode": "DE"

We will set the tax exemption to true.

"taxExempt": "true"

Sample API call

To update the contract header, make the following API call. deposit-api.sandbox.tuumplatform.com/ api/v2/contracts/{headerId}

See more about the endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for changing deposit contract payout details.

{
  "taxResidencyCountryCode": "DE",
  "taxExempt": "true"
}

curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v2/contracts/ID-1696407222' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMjFUMTQ6NDg6MTciLCJleHAiOjE3Mjk1MjIwOTcsInJvbGVzIjpbIkFETUlOIl19.pM0GzsEXo-IsdVy5X2l9FcORAul0_XaH_SEU_HNugjI' \
--header 'Content-Type: application/json' \
--data '{
  "taxResidencyCountryCode": "DE",
  "taxExempt": "true"
}'

Sample response

Below you find an example response body to the API call above.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "headerId": "ID-1696407222",
        "personId": "ID-2660",
        "accountId": "ID-1012",
        "applicationId": "ID-1696407202",
        "offerId": "ID-1718024054",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "contractNumber": "PR-EE-1001",
        "countryCode": "EE",
        "channelCode": "BACKOFFICE",
        "tenantCode": "MB",
        "depositClassCode": "PREMIUM_CUSTOMER",
        "headerActivationDate": "2026-07-08",
        "headerClosingDate": null,
        "activeVersion": {
            "versionId": "ID-1718024033",
            "headerId": "ID-1718024017",
            "versionNumber": 1,
            "statusCode": "ACTIVE",
            "preparationDate": "2026-07-08",
            "signingDate": null,
            "activationDate": "2026-07-08",
            "endDate": "2026-10-08",
            "closingDate": null,
            "period": 3,
            "periodTypeCode": "MONTH",
            "interestRate": 0.25,
            "interestPaymentFrequencyCode": "MONTH",
            "prolongCode": null,
            "countryCode": "EE",
            "cancelReasonCode": null,
            "lastCreditReceiveDate": "2026-07-10",
            "lastSigningDate": null,
            "changeTypeCode": "NEW_CONTRACT",
            "components": [
                {
                    "componentId": "ID-1718024154",
                    "versionId": "ID-1718024033",
                    "componentTypeCode": "PRI",
                    "initialMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": null,
                    "rateBaseCode": null,
                    "rate": null,
                    "accruedUntil": null,
                    "paymentDay": 8,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": null
                },
                {
                    "componentId": "ID-1718024155",
                    "versionId": "ID-1718024033",
                    "componentTypeCode": "INT",
                    "initialMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": {
                        "daysInMonth": "30",
                        "daysInYear": 360
                    },
                    "rateBaseCode": null,
                    "rate": 0.25,
                    "accruedUntil": null,
                    "paymentDay": 8,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": "2026-07-08"
                }
            ],
            "totalInterestMoney": {
                "amount": 3.13,
                "currencyCode": "EUR"
            },
            "totalInterestAccruedMoney": {
                "amount": 0.00,
                "currencyCode": "EUR"
            },
            "channelCode": "BACKOFFICE",
            "tenantCode": "MB",
            "terminationType": "WITHOUT_INTEREST",
            "nextPayoutDate": "2026-08-08",
            "payoutDetails": {
                "name": "Tech",
                "accountNumber": {
                    "value": "EE201225862567235311",
                    "type": "IBAN"
                },
                "financialInstitutionId": null,
                "referenceNumber": null,
                "countryCode": null
            }
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "DE",
        "taxExempt": true,
        "rateBaseCode": null
    }
}

Result

As a result, the tax residency country was updated and the tax exemption was set to true. The updated settings were applied to all existing deposit contract versions.

Adjust deposit contract interest

Use case

In this use case, we will create an interest adjustment for an active deposit contract. We will use the that was previously created.

Use case data

API parameters with values

The contract header is ID-1696407222. See find deposit contract page for more details.

...contracts/ID-1696407222/adjustments

"eventTypeCode": "INTEREST_INCREASE",
"componentTypeCode": "INT",

The interest increase amount is 0.25 EUR. Note: the contract interest adjustments must fall within the overall deposit interest adjustments rule.

"money": {
    "amount": 0.25,
    "currencyCode": "EUR"
  }

Sample API call

To adjust the deposit contract interest, make the following API call. deposit-api.sandbox.tuumplatform.com/api/v1/contracts/{headerId}/adjustments

See more about the endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for changing deposit contract payout details.

{
  "valueDateRule": "APPROVAL_DATE",
  "valueDate": "2027-03-06",
  "eventTypeCode": "INTEREST_INCREASE",
  "details": "Test",
  "componentTypeCode": "INT",
  "money": {
    "amount": 0.25,
    "currencyCode": "EUR"
  }
}

curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v1/contracts/ID-1696407222/adjustments' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDMtMTVUMTU6Mjk6MzgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE3MTA1MTY1Nzh9.B5YRuidueo8Ykoqv3z89Jm1rYSwPe2_B1w7Kk_sjP-k' \
--header 'Content-Type: application/json' \
--data '{
  "valueDateRule": "APPROVAL_DATE",
  "valueDate": "2027-03-06",
  "eventTypeCode": "INTEREST_INCREASE",
  "details": "Test",
  "componentTypeCode": "INT",
  "money": {
    "amount": 0.25,
    "currencyCode": "EUR"
  }
}'

Sample response

Below you will find an example response body to the API call above.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "adjustmentBookingId": "ID-1021",
        "componentTypeCode": "INT",
        "eventTypeCode": "INTEREST_INCREASE",
        "adjustmentType": "BOOKING",
        "postingDate": "2027-06-03",
        "valueDateRule": "APPROVAL_DATE",
        "valueDate": "2027-06-03",
        "statusCode": "PROCESSED",
        "initiatedByUserId": "1",
        "amountMoney": {
            "amount": 0.25,
            "currencyCode": "EUR"
        },
        "details": "Test",
        "source": {
            "sourceName": "DEPOSIT.CONTRACT_HEADER",
            "sourceRef": "ID-1696407222",
            "sourceLink": null
        },
        "originalAdjustmentBookingId": null,
        "headerId": "ID-1696407222",
        "personId": "ID-2660",
        "versionId": "ID-1696407267"
    }
}

Result

As a result a deposit contract interest adjustment: INTEREST_INCREASE with ID-1021 was created.

Change payout details

Use case

In this example, we will review how to change the payout details for an active deposit contract. We will use the that was previously created.

Use case data

API parameters

payoutDetails Parameter

The payoutDetails parameter is optional and can only be defined for an active deposit contract.

Supported Account Types

Payout details support the following account number types:

Click on the tabs below to see the formatting for each account number types.

Parameter validations:

If accountNumber.type is IBAN, financialInstitutionId is not required.
If accountNumber.type is IBAN and financialInstitutionId is provided, then countryCode is required.

Parameter validations:

If financialInstitutionId is provided, type can be one of the following values:
- BIC,
- SORT_CODE,
- BANK_CODE,
- ABA_CODE.
If accountNumber.type is BBAN and financialInstitutionId is ABA_CODE, countryCode can be one of the following:
- US (United States of America),
- PR (Puerto Rico),
- AS (American Samoa),
- GU (Guam),
- VI (Virgin Islands).
If accountNumber.type is BBAN and financialInstitutionId is SORT_CODE, countryCode is GB (Great Britain)

Default Behavior

Modifying Payout Details

Payout details can be modified or removed. To remove payout details from an active contract version, include the following in the request:

"payoutDetails":  null

Sample API call

To change the deposit contract payout details, make the following API call.

{
  "payoutDetails": {
    "name": "Test Account",
    "accountNumber": {
      "value": "EE111236525217358748",
      "type": "IBAN"
    
    }
    }
}

curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v1/contracts/ID-1696407222/versions/ID-1696407267/payout-details' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMDdUMTU6MDM6MTAiLCJleHAiOjE3MjgzMTMzOTAsInJvbGVzIjpbIkFETUlOIl19.KloWEzZXTCs6u0HeijjZyqn8Wy_bzhs8hdVsfSlFvS4' \
--header 'Content-Type: application/json' \
--data '{
  "payoutDetails": {
    "name": "Test Account",
    "accountNumber": {
      "value": "EE111236525217358748",
      "type": "IBAN"
    
    }
    }
}'

Sample response

Below you find an example response body to the API call above.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "headerId": "ID-1696407222",
        "personId": "ID-2660",
        "accountId": "ID-1012",
        "applicationId": null,
        "offerId": "ID-16964073051",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "contractNumber": "PR-EE-1000",
        "countryCode": "EE",
        "channelCode": "BACKOFFICE",
        "tenantCode": "MB",
        "depositClassCode": "PREMIUM_CUSTOMER",
        "headerActivationDate": "2026-04-04",
        "headerClosingDate": null,
        "activeVersion": {
            "versionId": "ID-1718024026",
            "headerId": "ID-1718024016",
            "versionNumber": 1,
            "statusCode": "ACTIVE",
            "preparationDate": "2026-04-04",
            "signingDate": null,
            "activationDate": "2026-04-04",
            "endDate": "2026-07-04",
            "closingDate": null,
            "period": 3,
            "periodTypeCode": "MONTH",
            "interestRate": 0.25,
            "interestPaymentFrequencyCode": "MONTH",
            "prolongCode": null,
            "countryCode": "EE",
            "cancelReasonCode": null,
            "lastCreditReceiveDate": "2026-04-06",
            "lastSigningDate": null,
            "changeTypeCode": "NEW_CONTRACT",
            "components": [
                {
                    "componentId": "ID-1718024140",
                    "versionId": "ID-1718024026",
                    "componentTypeCode": "PRI",
                    "initialMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": null,
                    "rateBaseCode": null,
                    "rate": null,
                    "accruedUntil": null,
                    "paymentDay": 4,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": null
                },
                {
                    "componentId": "ID-1718024141",
                    "versionId": "ID-1718024026",
                    "componentTypeCode": "INT",
                    "initialMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": {
                        "daysInMonth": "30",
                        "daysInYear": 360
                    },
                    "rateBaseCode": "FIX",
                    "rate": 0.25,
                    "accruedUntil": null,
                    "paymentDay": 4,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": "2026-04-04"
                }
            ],
            "totalInterestMoney": {
                "amount": 3.13,
                "currencyCode": "EUR"
            },
            "totalInterestAccruedMoney": {
                "amount": 0.00,
                "currencyCode": "EUR"
            },
            "channelCode": "BACKOFFICE",
            "tenantCode": "MB",
            "terminationType": "WITHOUT_INTEREST",
            "nextPayoutDate": "2026-05-04",
            "payoutDetails": {
                "name": "Test Account",
                "accountNumber": {
                    "value": "EE111236525217358748",
                    "type": "IBAN"
                },
                "financialInstitutionId": null,
                "referenceNumber": null,
                "countryCode": null
            }
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false
    }
}

Result

As a result, the deposit contract payout details were updated.

Change contract prolongation status

Use case

In this example, we will change the contract prolongation status for an active contract. We will use the that was previously created.

Use case data

API parameters with values

Prolongation types

The prolongationCode parameter can have one of the following values:

PRINCIPAL - The deposit contract is extended to a new period with only the initial deposit principal amount. All interest accrued during the term will be paid out to the payout account defined for the deposit.
PRINCIPAL_WITH_INTEREST - The deposit contract is extended to a new period with both the initial deposit principal amount and the interest accrued during the previous term. The interest is capitalised, meaning it is added to the initial principal amount, resulting in a new principal amount for the next term period.

Sample API call

To change the deposit contract prolongation details, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v2/contracts/{headerId}/versions/{versionId}/prolongation-status

See more about the endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for changing deposit contract payout details.

{
  "prolongationCode": "PRINCIPAL"
}

curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v2/contracts/ID-1696407222/versions/ID-1696407267/prolongation-status' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMDhUMTY6NDE6MDAiLCJleHAiOjE3Mjg0MDU2NjAsInJvbGVzIjpbIkFETUlOIl19.Dgxh4-g9be0P0mosxeihMtOol3XBkde3T84SYPHG3W4' \
--header 'Content-Type: application/json' \
--data '{
  "prolongationCode": "PRINCIPAL"
}'

Sample response

Below you find an example response body to the API call above.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "headerId": "ID-1696407222",
        "personId": "ID-2660",
        "accountId": "ID-1012",
        "applicationId": null,
        "offerId": "ID-16964073051",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "contractNumber": "PR-EE-1000",
        "countryCode": "EE",
        "channelCode": "BACKOFFICE",
        "tenantCode": "MB",
        "depositClassCode": "PREMIUM_CUSTOMER",
        "headerActivationDate": "2026-04-04",
        "headerClosingDate": null,
        "activeVersion": {
            "versionId": "ID-1718024026",
            "headerId": "ID-1718024016",
            "versionNumber": 1,
            "statusCode": "ACTIVE",
            "preparationDate": "2026-04-04",
            "signingDate": null,
            "activationDate": "2026-04-04",
            "endDate": "2026-07-04",
            "closingDate": null,
            "period": 3,
            "periodTypeCode": "MONTH",
            "interestRate": 0.25,
            "interestPaymentFrequencyCode": "MONTH",
            "prolongCode": "PRINCIPAL",
            "countryCode": "EE",
            "cancelReasonCode": null,
            "lastCreditReceiveDate": "2026-04-06",
            "lastSigningDate": null,
            "changeTypeCode": "NEW_CONTRACT",
            "components": [
                {
                    "componentId": "ID-1718024140",
                    "versionId": "ID-1718024026",
                    "componentTypeCode": "PRI",
                    "initialMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": null,
                    "rateBaseCode": null,
                    "rate": null,
                    "accruedUntil": null,
                    "paymentDay": 4,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": null
                },
                {
                    "componentId": "ID-1718024141",
                    "versionId": "ID-1718024026",
                    "componentTypeCode": "INT",
                    "initialMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 0.28,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": {
                        "daysInMonth": "30",
                        "daysInYear": 360
                    },
                    "rateBaseCode": null,
                    "rate": 0.25,
                    "accruedUntil": "2026-04-12",
                    "paymentDay": 4,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": "2026-04-12"
                }
            ],
            "totalInterestMoney": {
                "amount": 3.13,
                "currencyCode": "EUR"
            },
            "totalInterestAccruedMoney": {
                "amount": 0.28,
                "currencyCode": "EUR"
            },
            "channelCode": "BACKOFFICE",
            "tenantCode": "MB",
            "terminationType": "WITHOUT_INTEREST",
            "nextPayoutDate": "2026-05-04",
            "payoutDetails": {
                "name": "Test Account",
                "accountNumber": {
                    "value": "EE111236525217358748",
                    "type": "IBAN"
                },
                "financialInstitutionId": null,
                "referenceNumber": null,
                "countryCode": null
            }
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false,
        "rateBaseCode": null
    }
}

Result

As a result, the deposit contract prolongation status was updated.