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

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

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:

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.

Sample API call

Sample request

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

Sample response

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

Response

Result

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

Find deposit application

Use case

Use case data

API parameters with values

...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.

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 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

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.

Sample API call

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

Sample response

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

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.

Sample API call

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

Sample request

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

Sample response

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

Response

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.

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

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

Use case data

API parameters with values

...v2/persons/ID-2660/contracts

This API call requires mandatory query parameters pageSize and pageNumber.

...?pageSize=1&pageNumber=1

Sample API call

Sample response

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

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "values": [
            {
                "headerId": "ID-1696407222",
                "personId": "ID-2660",
                "accountId": "ID-1012",
                "applicationId": "ID-1696407202",
                "offerId": "ID-1696407305",
                "depositGroupCode": "TIME_DEPOSIT",
                "depositTypeCode": "PREMIUM_TEST",
                "contractNumber": "PR-EE-1000",
                "countryCode": "EE",
                "channelCode": "SYSTEM",
                "tenantCode": "MB",
                "depositClassCode": null,
                "headerActivationDate": null,
                "headerClosingDate": null,
                "activeVersion": {
                    "versionId": "ID-1718023938",
                    "headerId": "ID-1718023942",
                    "versionNumber": 1,
                    "statusCode": "ACTIVE",
                    "preparationDate": "2024-11-15",
                    "signingDate": null,
                    "activationDate": null,
                    "endDate": "2025-02-15",
                    "closingDate": null,
                    "period": 3,
                    "periodTypeCode": "MONTH",
                    "interestRate": 0.25,
                    "interestPaymentFrequencyCode": "END",
                    "prolongCode": null,
                    "countryCode": "EE",
                    "cancelReasonCode": "CREDIT_PERIOD_PASSED",
                    "lastCreditReceiveDate": "2024-11-17",
                    "lastSigningDate": null,
                    "changeTypeCode": "NEW_CONTRACT",
                    "components": [
                        {
                            "componentId": "ID-1718023964",
                            "versionId": "ID-1718023938",
                            "componentTypeCode": "PRI",
                            "initialMoney": {
                                "amount": 5000.00,
                                "currencyCode": "EUR"
                            },
                            "balanceMoney": {
                                "amount": 0.00,
                                "currencyCode": "EUR"
                            },
                            "calculationMethod": null,
                            "rateBaseCode": null,
                            "rate": null,
                            "accruedUntil": null,
                            "paymentDay": 15,
                            "paymentInterval": 1,
                            "baseInvalidFromDate": null
                        },
                        {
                            "componentId": "ID-1718023965",
                            "versionId": "ID-1718023938",
                            "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": 15,
                            "paymentInterval": 1,
                            "baseInvalidFromDate": null
                        }
                    ],
                    "totalInterestMoney": {
                        "amount": 3.13,
                        "currencyCode": "EUR"
                    },
                    "totalInterestAccruedMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "channelCode": "SYSTEM",
                    "tenantCode": "MB",
                    "terminationType": "WITHOUT_INTEREST",
                    "nextPayoutDate": null,
                    "payoutDetails": null
                },
                "personTypeCode": "P",
                "taxResidencyCountryCode": "EE",
                "taxExempt": false
            }
        ],
        "pageNumber": 1,
        "pageSize": 1,
        "endReached": true,
        "sort": null
    }
}

Result

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

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.

"depositTypeCode": "PREMIUM"

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

"accountId": "ID-1012"

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.

"period": 3,
"periodTypeCode": "MONTH",
"interestPaymentFreqCode": "END",
"countryCode": "EE"

The deposit amount is 5000 EUR.

"initialMoney": {
    "amount": 5000,
    "currencyCode": "EUR"

"payoutDetails": {
    "name": "Test user",
    "accountNumber": {
      "value": "EE961221248796768756",
      "type": "IBAN"
    }
    }

The default deposit interest rate is set at 0.35.

"interestRate": 0.35

Sample API call

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

See more information about the 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 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

We will find an existing deposit contract that was with the ID-2660.

...v2/persons/ID-2660/contracts

This API call requires mandatory query parameters pageSize and pageNumber.

...?pageSize=1&pageNumber=1

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

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "values": [
            {
                "headerId": "ID-1696407222",
                "personId": "ID-2660",
                "accountId": "ID-1012",
                "applicationId": "ID-1696407202",
                "offerId": "ID-1696407305",
                "depositGroupCode": "TIME_DEPOSIT",
                "depositTypeCode": "PREMIUM_TEST",
                "contractNumber": "PR-EE-1000",
                "countryCode": "EE",
                "channelCode": "SYSTEM",
                "tenantCode": "MB",
                "depositClassCode": null,
                "headerActivationDate": null,
                "headerClosingDate": null,
                "activeVersion": {
                    "versionId": "ID-1718023938",
                    "headerId": "ID-1718023942",
                    "versionNumber": 1,
                    "statusCode": "ACTIVE",
                    "preparationDate": "2024-11-15",
                    "signingDate": null,
                    "activationDate": null,
                    "endDate": "2025-02-15",
                    "closingDate": null,
                    "period": 3,
                    "periodTypeCode": "MONTH",
                    "interestRate": 0.25,
                    "interestPaymentFrequencyCode": "END",
                    "prolongCode": null,
                    "countryCode": "EE",
                    "cancelReasonCode": "CREDIT_PERIOD_PASSED",
                    "lastCreditReceiveDate": "2024-11-17",
                    "lastSigningDate": null,
                    "changeTypeCode": "NEW_CONTRACT",
                    "components": [
                        {
                            "componentId": "ID-1718023964",
                            "versionId": "ID-1718023938",
                            "componentTypeCode": "PRI",
                            "initialMoney": {
                                "amount": 5000.00,
                                "currencyCode": "EUR"
                            },
                            "balanceMoney": {
                                "amount": 0.00,
                                "currencyCode": "EUR"
                            },
                            "calculationMethod": null,
                            "rateBaseCode": null,
                            "rate": null,
                            "accruedUntil": null,
                            "paymentDay": 15,
                            "paymentInterval": 1,
                            "baseInvalidFromDate": null
                        },
                        {
                            "componentId": "ID-1718023965",
                            "versionId": "ID-1718023938",
                            "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": 15,
                            "paymentInterval": 1,
                            "baseInvalidFromDate": null
                        }
                    ],
                    "totalInterestMoney": {
                        "amount": 3.13,
                        "currencyCode": "EUR"
                    },
                    "totalInterestAccruedMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "channelCode": "SYSTEM",
                    "tenantCode": "MB",
                    "terminationType": "WITHOUT_INTEREST",
                    "nextPayoutDate": null,
                    "payoutDetails": null
                },
                "personTypeCode": "P",
                "taxResidencyCountryCode": "EE",
                "taxExempt": false
            }
        ],
        "pageNumber": 1,
        "pageSize": 1,
        "endReached": true,
        "sort": null
    }
}

Result

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