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 deposit contract that was previously created.

Use case data	API parameters
The contract header is ID-1696407222. See the find deposit contract for more details.	api/v1/contracts/ID-1696407222...
The active contract version is ID-1696407267. See the find deposit contract 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 below.	"payoutDetails": { "name": "Test Account", "accountNumber": { "value": "EE111236525217358748", "type": "IBAN"

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:

• IBAN,

• BBAN.

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

IBAN

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

Parameter validations:

1. If accountNumber.type is IBAN, financialInstitutionId is not required.

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

BBAN

"payoutDetails": {  
          "name": "Malloy Harbor", 
          "accountNumber": {   
            "type": "BBAN", 
            "value": "3159584114"    
          },
          "financialInstitutionId": { 
            "type": "BANK_CODE",
            "value": "5051"
          },
          "countryCode": "DK", 
          "referenceNumber": null 
        }

Parameter validations:

1. If financialInstitutionId is provided, type can be one of the following values:

   • BIC,

   • SORT_CODE,

   • BANK_CODE,

   • ABA_CODE.

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

3. If accountNumber.type is BBAN and financialInstitutionId is SORT_CODE, countryCode is GB (Great Britain)

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:

"payoutDetails":  null

Sample API call

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

JSON

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

cURL

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.