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:
In this example, we will review how to change the payout details for an active deposit contract. We will use the deposit contract that was previously created.
The contract header is ID-1696407222. See the for more details.
api/v1/contracts/ID-1696407222...
The active contract version is ID-1696407267. See the for more details.
...versions/ID-1696407267/payout-details
The new payout details.
Note: the payoutDetails parameter is not mandatory. This parameter can be only defined for an active deposit contract. See more information about the payoutDetails parameter .
The payoutDetails parameter is optional and can only be defined for an active deposit contract.
Payout details support the following account number types:
Click on the tabs below to see the formatting for each account number types.
"payoutDetails": {
"name": "Test Account",
"accountNumber": {
"value": "EE111236525217358748",
"type": "IBAN"Parameter validations:
If accountNumber.type is IBAN, financialInstitutionId is not required.
If accountNumber.type is IBAN and financialInstitutionId is provided, then countryCode is required.
"payoutDetails": {
"name": "Malloy Harbor",
"accountNumber": {
"type": "BBAN",
"value": "3159584114"
},
"financialInstitutionId": {
"type": "BANK_CODE",
"value": "5051"
},
"countryCode": "DK",
"referenceNumber": null
}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)
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.
Payout details can be modified or removed. To remove payout details from an active contract version, include the following in the request:
"payoutDetails": nullTo 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"
}
}
}'Below you find an example response body to the API call above.
As a result, the deposit contract payout details were updated.
"payoutDetails": {
"name": "Test Account",
"accountNumber": {
"value": "EE111236525217358748",
"type": "IBAN"In this example, we will review how to terminate an active contract prematurely (before the contract reaches its end date). We will use the deposit contract that was previously created.
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.
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
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"
}'Below you will find an example response body to the API call above
As a result, the deposit contract is set to the TERMINATING status.
In this use case, we will create an interest adjustment for an active deposit contract. We will use the deposit contract that was previously created.
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.
To adjust the deposit contract interest, make the following API call.
deposit-api.sandbox.tuumplatform.com/api/v1/contracts/{headerId}/adjustments
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"
}
}'Below you will find an example response body to the API call above.
As a result a deposit contract interest adjustment: INTEREST_INCREASE with ID-1021 was created.
"terminationType": "WITHOUT_INTEREST""eventTypeCode": "INTEREST_INCREASE",
"componentTypeCode": "INT","money": {
"amount": 0.25,
"currencyCode": "EUR"
}
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.
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.
We will set the tax exemption to true.
To update the contract header, make the following API call.
deposit-api.sandbox.tuumplatform.com/
api/v2/contracts/{headerId}
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"
}'Below you find an example response body to the API call above.
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.
"taxResidencyCountryCode": "DE""taxExempt": "true"In this example, we will change the contract prolongation status for an active contract. We will use the deposit contract that was previously created.
The contract header is ID-1696407222. See the page for more details.
...v2/contracts/ID-1696407222/...
The active contract version is ID-1696407267. See the page for more details.
...versions/ID-1696407267/payment-instructions
We will change prolongation status to principal with interest. With this setting when the deposit contract is automatically prolonged, the interest is moved to principal.
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.
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
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"
}'Below you find an example response body to the API call above.
As a result, the deposit contract prolongation status was updated.
"prolongationCode": "PRINCIPAL"