1 of 9

Deposit flow

In this block, you will learn how to open a deposit contract flow. There are two flows available:

Deposit flow - from application,
Deposit flow - from offer.

Deposit flow - from application

The first deposit flow starts from a deposit application and includes the following steps:

Create deposit application - once the deposit application is created, the Tuum system automatically creates a related deposit offer.
Accept deposit offer - once the deposit offer is accepted, the Tuum system automatically creates a related deposit contract. Or decline deposit offer - reject the offer and terminate the flow.

Deposit flow - from offer

You can use this flow if your organisation processes deposit applications outside the Tuum system.

When using the deposit offer flow, you can set or change the interest rate within the deposit product min/max range. On the contrary, the deposit application flow always uses the default interest rate with no option to change it.

This deposit contract flow starts from a deposit offer and includes the following steps:

Create deposit offer - to enter the required deposit information into the Tuum system.
Accept deposit offer - once the deposit offer is accepted, the Tuum system will automatically create a deposit contract based on the deposit offer. Or decline deposit offer - to reject the deposit offer and terminate the flow.

Below, you will find the following chapters:

Create deposit application

Use case

In this example, we will review how to create a deposit application with a minimum data set.

Use case data

API parameters with values

We will create a deposit application for a test person whose account ID is ID-2660.

...persons/ID-2660/applications

The amount that the test person is going to deposit is 5000 EUR.

The deposit application is opened for a PREMIUM created earlier.

The servicing account ID that is tied to the deposit. Note: see the article to learn more about the account creation.

The deposit is offered with the 3 month duration. The interest will be paid at the end of the contract period. The deposit's jurisdiction country is Estonia.

The tax residency code determines which tax rate is enabled for this country when deducting the tax from the interest during the pay out. The tax exempt is false by default. Note: the taxResidencyCountryCode and taxExempt parameters are editable even after the deposit contract is created or activated.

Sample API call

deposit-api.sandbox.tuumplatform.com/api/v2/persons/{personId}/applications

See more information about the create deposit application endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for creating a deposit application.

{
  "initialMoney": {
    "amount": 5000,
    "currencyCode": "EUR"
  },
  "depositTypeCode": "PREMIUM",
  "accountId": "ID-5334",
  "period": 3,
  "periodTypeCode": "MONTH",
  "interestPaymentFreqCode": "END",
  "countryCode": "EE",
  "taxResidencyCountryCode": "EE",
  "taxExempt": "false"
}

curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v2/persons/ID-2660/applications' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHBpcnlEVGltZSI6IjIwMjQtMDUtMjlUMTc6MjM6MDQiLCJleHAiOjE3MTcwMDMzODQsInJvbGVzIjpbIkFETUlOIl19.RyH47_HA4Run4sJtIGeiJmxhlN8sCin_GnGLH_6qKZc' \
--header 'Content-Type: application/json' \
--data '{
  "initialMoney": {
    "amount": 5000,
    "currencyCode": "EUR"
  },
  "depositTypeCode": "PREMIUM",
  "accountId": "ID-5334",
  "period": 3,
  "periodTypeCode": "MONTH",
  "interestPaymentFreqCode": "END",
  "countryCode": "EE",
  "taxResidencyCountryCode": "EE",
   "taxExempt": "false"
}'

Sample response

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

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "applicationId": "ID-1696407202",
        "personId": "ID-2660",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "statusCode": "ACCEPTED",
        "accountId": "ID-5334",
        "period": 3,
        "periodTypeCode": "MONTH",
        "endDate": null,
        "initialMoney": {
            "amount": 5000.00,
            "currencyCode": "EUR"
        },
        "interestPaymentFreqCode": "END",
        "prolongationCode": null,
        "countryCode": "EE",
        "interestRate": 0.25,
        "postingDate": "2024-11-14",
        "channelCode": "SYSTEM",
        "tenantCode": "MB",
        "offerId": null,
        "depositClassCode": "PREMIUM_CUSTOMER",
        "payoutDetails": null,
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false
    }
}

Result

As a result, a new deposit application ID-1696407202 was created.

Find deposit application

Use case

In this case, we will review how to find the ID of a created deposit application using person ID.

Use case data

API parameters with values

We will find an existing that was created for the test person with ID-2660.

...v2/persons/ID-2660/applications

This API call requires mandatory query parameters pageSize and pageNumber.

...?pageSize=1&pageNumber=1

Sample API call

To find a deposit application, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v3/persons/{personId}/applications

See more about the find deposit application endpoint in the Tuum developer portal.

Sample response

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

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "values": [
            {
                "applicationId": "ID-1696407202",
                "personId": "ID-2660",
                "depositGroupCode": "TIME_DEPOSIT",
                "depositTypeCode": "PREMIUM_TEST",
                "statusCode": "ACCEPTED",
                "accountId": "ID-5334",
                "period": 3,
                "periodTypeCode": "MONTH",
                "endDate": null,
                "initialMoney": {
                    "amount": 5000.00,
                    "currencyCode": "EUR"
                },
                "interestPaymentFreqCode": "END",
                "prolongationCode": null,
                "countryCode": "EE",
                "interestRate": 0.25,
                "postingDate": "2024-11-14",
                "channelCode": "SYSTEM",
                "tenantCode": "MB",
                "offerId": null,
                "depositClassCode": "PREMIUM_CUSTOMER",
                "payoutDetails": null,
                "personTypeCode": "P",
                "taxResidencyCountryCode": "EE",
                "taxExempt": false
            }
        ],
        "pageNumber": 1,
        "pageSize": 1,
        "endReached": true,
        "sort": null
    }
}

Result

As a result we found the deposit application with the ID-1696407202 and fetched other information related to the deposit application.

Create deposit offer

Use case

In this example we will review the first step of the deposit contract origination flow that starts with creating a deposit offer.

Use case data

API parameters with values

We will create a deposit offer for a test person whose account ID is ID-2660.

...persons/ID-2660/offers

The deposit offer is opened for a PREMIUMthat was created earlier.

The account ID that is tied to the deposit. Note: see the article to learn more about the account creation.

The deposit is offered with the 3 month duration. The interest will be payed at the end of the contract period. The deposit country is Estonia.

The deposit amount is 5000 EUR.

Upon maturity of the deposit contract, the deposit API transfers the payout to the designated payout account. If payout details are not provided, the payout is automatically directed to the servicing account.

The default deposit interest rate is set at 0.35.

Note: If the deposit product has a defined minimum and maximum interest rate range, you can set a custom interest rate within this range to override the default rate. If no interest range is defined for the deposit product, the default interest rate of 0.35 is applied.

Sample API call

POST /deposit-api.sandbox.tuumplatform.com/api/v2/persons/{personId}/offers

See more information about the create deposit offer endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for creating a deposit offer.

{
    "depositTypeCode": "PREMIUM",
    "accountId": "ID-1012",
    "period": 3,
    "periodTypeCode": "MONTH",
    "interestPaymentFreqCode": "END",
    "initialMoney": {
        "amount": 5000,
        "currencyCode": "EUR"
    },
    "countryCode": "EE",
    "payoutDetails": {
    "name": "Test user",
    "accountNumber": {
      "value": "EE961221248796768756",
      "type": "IBAN"
    }
    },
    "taxResidencyCountryCode": "EE",
    "interestRate": 0.35
}

curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v2/persons/ID-1015/offers' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMjlUMjA6MTI6MzEiLCJleHAiOjE3MzAyMzI3NTEsInJvbGVzIjpbIkFETUlOIl19.ViX6Uwnv1n_h2cBxprFUJRxlXJGce0_A1F5o-HA04oE' \
--header 'Content-Type: application/json' \
--data '{
    "depositTypeCode": "PREMIUM",
    "accountId": "ID-1012",
    "period": 3,
    "periodTypeCode": "MONTH",
    "interestPaymentFreqCode": "END",
    "initialMoney": {
        "amount": 5000,
        "currencyCode": "EUR"
    },
    "countryCode": "EE",
    "payoutDetails": {
    "name": "Test user",
    "accountNumber": {
      "value": "EE961221248796768756",
      "type": "IBAN"
    }
    },
    "taxResidencyCountryCode": "EE",
    "interestRate": 0.35
}'

Sample response

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

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "offerId": "ID-1718024058",
        "personId": "ID-2660",
        "applicationId": null,
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "terminationType": "WITHOUT_INTEREST",
        "statusCode": "PREPARING",
        "reasonCode": null,
        "accountId": "ID-1012",
        "interestRate": 0.35,
        "period": 3,
        "periodTypeCode": "MONTH",
        "endDate": null,
        "initialMoney": {
            "amount": 5000.00,
            "currencyCode": "EUR"
        },
        "interestPaymentFreqCode": "END",
        "prolongationCode": null,
        "countryCode": "EE",
        "maturityDate": "2027-04-21",
        "returnAmount": {
            "amount": 5004.38,
            "currencyCode": "EUR"
        },
        "postingDate": "2027-01-21",
        "lastValidDate": "2027-01-22",
        "channelCode": "SYSTEM",
        "tenantCode": "MB",
        "contractHeaderId": null,
        "contractNumber": null,
        "depositClassCode": "PREMIUM_CUSTOMER",
        "payoutDetails": {
            "name": "Test user",
            "accountNumber": {
                "value": "EE961221248796768756",
                "type": "IBAN"
            },
            "financialInstitutionId": null,
            "referenceNumber": null,
            "countryCode": null
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false,
        "marginRate": null
    }
}

Result

As an outcome, a new deposit offer ID-1718024058 was created.

Find deposit offer

Use case

In this example, we will review how to find a deposit offer using the application ID.

Use case data

API parameters with values

Searching the deposit offer that was created for the with ID-1696407202.

...applications/ID-1696407202/offers

Sample API call

To find a deposit offer that was automatically created by the deposit application, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v2/applications/{applicationId}/offers

See more about the find offer endpoint in the Tuum developer portal.

Sample response

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

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "offerId": "ID-1696407305",
        "personId": "ID-2660",
        "applicationId": "ID-1696407202",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM_TEST",
        "terminationType": "WITHOUT_INTEREST",
        "statusCode": "PRESENTED",
        "reasonCode": null,
        "accountId": "ID-1012",
        "interestRate": 0.25,
        "period": 3,
        "periodTypeCode": "MONTH",
        "endDate": null,
        "initialMoney": {
            "amount": 5000.00,
            "currencyCode": "EUR"
        },
        "interestPaymentFreqCode": "END",
        "prolongationCode": null,
        "countryCode": "EE",
        "maturityDate": "2025-02-15",
        "returnAmount": {
            "amount": 5003.13,
            "currencyCode": "EUR"
        },
        "postingDate": "2024-11-15",
        "lastValidDate": "2024-11-16",
        "channelCode": "SYSTEM",
        "tenantCode": "MB",
        "contractHeaderId": null,
        "contractNumber": null,
        "depositClassCode": "PREMIUM_CUSTOMER",
        "payoutDetails": null,
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false
    }
}

Result

As an outcome, we found the deposit offer ID ID-1696407305 and fetched related details.

Edit deposit offer

Use case

In this example, we will review how to edit a deposit offer.

Use case data

API parameters with values

We will change the deposit offer ID-1718024058.

...offers/ID-1718024058

We will change the deposit offer initial amount from 5000 EUR to 6000 EUR.

Sample API call

To edit a deposit offer, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v2/offers/{offerId}

See more about the edit deposit offer endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for editing a deposit offer.

{
  "initialMoney": {
    "amount": 6000,
    "currencyCode": "EUR"
  },
  "period": 3,
  "interestPaymentFreqCode": "END",
  "taxResidencyCountryCode": "EE",
  "prolongationCode": "PRINCIPAL",
  "taxExempt": "false",
  "interestRate": 0.35
}

curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v2/offers/ID-1718024058' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMzBUMTM6MzI6MjgiLCJleHAiOjE3MzAyOTUxNDgsInJvbGVzIjpbIkFETUlOIl19.7g3ys-QseNqtzu6P5l5lEdpj1tk5izFT10f4AEc9RVo' \
--header 'Content-Type: application/json' \
--data '{
  "initialMoney": {
    "amount": 6000,
    "currencyCode": "EUR"
  },
  "period": 3,
  "interestPaymentFreqCode": "END",
  "taxResidencyCountryCode": "EE",
  "prolongationCode": "PRINCIPAL",
  "taxExempt": "false",
  "interestRate": 0.35
}'

Sample response

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

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "offerId": "ID-1718024058",
        "personId": "ID-2660",
        "applicationId": null,
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "COPY_PREMIUM_NEW",
        "terminationType": "WITHOUT_INTEREST",
        "statusCode": "PRESENTED",
        "reasonCode": null,
        "accountId": "ID-1012",
        "interestRate": 0.35,
        "period": 3,
        "periodTypeCode": "MONTH",
        "endDate": null,
        "initialMoney": {
            "amount": 6000.00,
            "currencyCode": "EUR"
        },
        "interestPaymentFreqCode": "END",
        "prolongationCode": "PRINCIPAL",
        "countryCode": "EE",
        "maturityDate": "2027-04-26",
        "returnAmount": {
            "amount": 6005.25,
            "currencyCode": "EUR"
        },
        "postingDate": "2027-01-26",
        "lastValidDate": "2027-01-27",
        "channelCode": "BACKOFFICE",
        "tenantCode": "MB",
        "contractHeaderId": null,
        "contractNumber": null,
        "depositClassCode": "PREMIUM_CUSTOMER",
        "payoutDetails": {
            "name": "Test User",
            "accountNumber": {
                "value": "EE961221248796768756",
                "type": "IBAN"
            },
            "financialInstitutionId": null,
            "referenceNumber": null,
            "countryCode": null
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false,
        "marginRate": null
    }
}

Result

As a result the deposit offer ID-1718024058 was updated. The initial offer amount was changed.

Accept deposit offer

Use case

In this example, we will review how to accept a deposit offer.

Use case data

API parameters with values

We will accept the deposit offer ID-1696407305.

...v1/offers/ID-1696407305/accept

Sample API call

To accept a deposit offer, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v2/offers/{offerId}/accept

See more about the accept deposit offer endpoint in the Tuum developer portal.

Sample response

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

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "offerId": "ID-1696407305",
        "personId": "ID-2660",
        "applicationId": "ID-1696407202",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM_TEST",
        "terminationType": "WITHOUT_INTEREST",
        "statusCode": "ACCEPTED",
        "reasonCode": null,
        "accountId": "ID-5334",
        "interestRate": 0.25,
        "period": 3,
        "periodTypeCode": "MONTH",
        "endDate": null,
        "initialMoney": {
            "amount": 5000.00,
            "currencyCode": "EUR"
        },
        "interestPaymentFreqCode": "END",
        "prolongationCode": null,
        "countryCode": "EE",
        "maturityDate": "2025-02-15",
        "returnAmount": {
            "amount": 5003.13,
            "currencyCode": "EUR"
        },
        "postingDate": "2024-11-15",
        "lastValidDate": "2024-11-16",
        "channelCode": "SYSTEM",
        "tenantCode": "MB",
        "contractHeaderId": null,
        "contractNumber": null,
        "depositClassCode": "PREMIUM_CUSTOMER",
        "payoutDetails": null,
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false
    }
}

Result

As a result the deposit offer ID-1696407305 was accepted.

Once the deposit offer is accepted, the Tuum system automatically creates a deposit contract based on the related deposit offer.

Decline deposit offer

Use case

In this example, we will review how to decline a deposit offer.

Use case data

API parameters with values

We will decline a deposit offer ID-1718023944.

...offers/ID-1718023944/decline

Sample API call

deposit-api.sandbox.tuumplatform.com/api/v3/offers/{offerId}/decline

See more information about the decline deposit offer endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for declining a deposit offer.

{
  "reasonCode": "DOCUMENT_MISSING"
}

curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v3/offers/ID-1718023944/decline' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMDYtMjdUMDk6NDU6NTgiLCJleHAiOjE3MTk0ODE1NTgsInJvbGVzIjpbIkFETUlOIl19.Iek0Ie70FXaTaduvpSat17RcEV8KPp9c9JsL14S1QOU' \
--header 'Content-Type: application/json' \
--data '{
  "reasonCode": "DOCUMENT_MISSING"
}'

Sample response

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

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "offerId": "ID-1718023943",
        "personId": "ID-1015",
        "applicationId": null,
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "terminationType": "WITHOUT_INTEREST",
        "statusCode": "DECLINED",
        "reasonCode": null,
        "accountId": "ID-1012",
        "interestRate": 0.25,
        "period": 3,
        "periodTypeCode": "MONTH",
        "endDate": null,
        "initialMoney": {
            "amount": 5000.00,
            "currencyCode": "EUR"
        },
        "interestPaymentFreqCode": "MONTH",
        "prolongationCode": "PRINCIPAL",
        "countryCode": "EE",
        "maturityDate": "2025-03-30",
        "returnAmount": {
            "amount": 5003.12,
            "currencyCode": "EUR"
        },
        "postingDate": "2024-12-30",
        "lastValidDate": "2024-12-31",
        "channelCode": "BACKOFFICE",
        "tenantCode": "MB",
        "contractHeaderId": null,
        "contractNumber": null,
        "depositClassCode": "PREMIUM_CUSTOMER",
        "payoutDetails": {
            "name": "Tech Writing",
            "accountNumber": {
                "value": "XX47XXXX99999000000000000000122",
                "type": "IBAN"
            },
            "financialInstitutionId": null,
            "referenceNumber": null,
            "countryCode": null
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false
    }
}

Result

As a result, a deposit offer ID-1718023943 was declined.

Find deposit contract

Use case

In this example, we will find the deposit contract that was automatically created by the Tuum system after .

Use case data

API parameters with values

Sample API call

/deposit-api.sandbox.tuumplatform.com/api/v3/persons/{personId}/contracts

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

Sample response

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

Response

Result

As a result, we found the deposit contract number PR-EE-1000 with headerId ID-1696407222 and activeVersionId ID-1696407267.