Documentation

Interest Configuration

Column's APIs allow you to create flexible interest configurations with various accrual methods and interest rates (including fixed rates, floating rates and tier-based rates).

Accrual Methods

Our system supports the following widely used accrual methods in the industry.

  • actual_360: Actual/360 is calculated by dividing the annual interest rate by 360 to get the daily interest rate, and then multiplying that number by the days in the month. This results in a larger annual interest payment because there are 365 or 366 days per year.
  • actual_365: Actual/365 is calculated by dividing the annual interest rate by 365 to get the daily interest rate, and then multiplying that number by the number of days in the current month. This results in a slightly larger annual interest payment in leap years because there are 366 days.
  • actual_actual: Actual/actual is calculated by dividing the annual interest rate by the actual number of days in the current year to get the daily interest rate, and then multiplying that number by the number of days in the current month. This results in an exact annual interest payment as specified by an interest rate.

The following table compares the above accrual methods. Assume the current account balance is $1,000,000, with an interest rate of 4.00%, and there are 31 days in the current month. Note LY means Leap Year.

MethodDaily RateDaily AccrualMonthly AccrualAnnual AccrualEffective Rate
actual_3600.01111%$111.11$3,444.44$40,555.56
(LY $40,666.67)		4.056%
(LY 4.067%)
actual_3650.01096%$109.59$3,397.26$40,000.00
(LY $40,109.59)		4.00%
(LY 4.011%)
actual_actual0.01096% (LY 0.01093%)$109.59
(LY $109.29)		$3,397.26
(LY $3,387.98)		$40,000.004.00%

Interest Rates

Our system supports the following interest rates.

  • Fixed Rate: A fixed interest rate is simply given as a flat percentage of outstanding balances (e.g., 4.50%).
  • Floating Rate: A floating interest rate is calculated off of a given pivot interest rates. Pivot rates are specified by your platform and can be set equal to EFFR. Floating interest rates are defined as percentages of a pivot rate (e.g, 90% of EFFR), or a pivot rate +/- premium rates (e.g., EFFR - 1.25%).
  • Tier-based Rate: A tier-based rate allows for different interest rates to be applied to different balance amounts. Within each tier, fixed interest rates or floating interest rates may be applied. By default, tier-based interest is calculated using a waterfall approach. You may change this with the parameter is_not_waterfall.

For example, you may define a tier-based interest rate with the actual_365 method as:

  • 2.00% for balances < $100K
  • EFFR * 90% for balances between $100K and $250K
  • EFFR - 1.25% for balances above $250K.

If the available balance of an account is $300K, and EFFR is 5.25%, its daily interest will be calculated using a waterfall approach as:

  • First tier: $100K * 2.00% / 365 = $5.479452
  • Second tier: ($250K - $100K) * 5.25% * 90% / 365 = $19.417808
  • Third tier: ($300K - $250K) * (5.25% - 1.25%) / 365 = $5.494505
  • Total daily interest: $5.479452 + $19.417808 + $5.494505 = $30.391765

However, if is_not_waterfall = true for the above tier-based config, daily interest will be calculated by applying tier rates to the entire account balance:

  • Account balance < $100K: balance * 2.00% / 365
  • Account balance between $100K and $250K: balance * 5.25% * 90% / 365
  • Account balance >= $250K: balance * (5.25% - 1.25%) / 365

Our system uses two main data models to define interest rates: pivot interest rates and interest configs.

Pivot Interest Rates

Pivot interest rates are global in your platform and used to calculate floating interest rates. You can use EFFR as the pivot rate for your platform or specify any other rate you prefer. It is your responsibility to update the pivot rate as Fed rates change (as applicable). A pivot rate must be updated by 4pm PST on its effective date to be applicable that day. Each pivot rate object has its effective date and interest rates. You can use our APIs to update or schedule future pivot rates. We allow only one pivot rate for a given effective date. When we calculate floating interest rates, we will use the latest pivot rate with an effective date before or on the interest accrual date. For example, assume you schedule the following pivot rates:

  • Effective date: 2024-01-01, pivot rate: 5.00%
  • Effective date: 2024-04-01, pivot rate: 4.75%
  • Effective date: 2024-07-01, pivot rate: 4.50%
  • Effective date: 2024-10-01, pivot rate: 4.25%

On each day we accrue interest we will look for the latest rate with an effective date before or on the interest accrual date, so with the above set up, different rates will be applied to calculate floating interest rates:

  • Before 2024-01-01, no pivot rate available. Float interest calculation will fail.
  • Between 2024-01-01 and 2024-03-31, pivot rate: 5.00%
  • Between 2024-04-01 and 2024-06-30: pivot rate: 4.75%
  • Between 2024-07-01 and 2024-09-30: pivot rate: 4.50%
  • On and after 2024-10-01, pivot rate: 4.25%

Interest Configs

An interest config object specifies an accrual method and fixed, floating or tier-based rates. An interest config can be assigned to one account, multiple accounts, or all accounts on your platform by setting the default interest config of your platform.

  • If an interest config is updated, the new config will automatically apply to all accounts to which the config is assigned. In order to reduce overhead of updating interest configs, we encourage you to share interest configs across accounts as possible.
  • Pivot rate updates will automatically be picked up by interest configs using floating rates. We will always find the latest pivot rate with an effective date before or on the interest accrual date as shown above. You do not need to update these interest configs individually.

You can use our APIs to update or schedule future interest rate changes. Each update is saved as a snapshot of the interest config. Within each snapshot, you can specify an accrual method and fixed, floating or tier-based rates. We allow only one snapshot for a given effective date. You can use our API to query the snapshot used for the current date, or a given accrual date, and its associated pivot rate. If a tier-based rate is used, there must be one tier with zero threshold. In addition, we don’t allow multiple tiers with the same threshold value within a snapshot.

In addition, you can also specify ceiling interest rates and floor interest rates for each snapshot, which define the maximum effective interest rate and minimum effective interest rate allowed respectively.

For example, if you update a config as:

  • Ceiling interest rate: 4.00%
  • Floor interest rate: 0.50%
  • Rate: 90% of the pivot rate of your platform

The effective interest rate of this config will be:

  • If pivot rate is 4.00%, effective rate is 90% * 4.00% = 3.60%.
  • If pivot rate is 5.25%, effective rate is 4.00% (90% * 5.25% = 4.725% > 4.00%)
  • If pivot rate is 0.25%, effective rate is 0.50% (90% * 0.25% = 0.225% < 0.50%)

Platform & Account Settings

You have two options to set interest configs on bank accounts:

  1. Column can set a default interest config for your platform. You will create the config and it will be applied to all interest-bearing accounts if an account does not have its own specific interest config.
  2. You can set account specific interest configs. You can use our Account Create API or Account Update API to set specific configs for bank accounts to preempt the default interest config.

Examples

The following examples demonstrate how to set flexible interest configs for various scenarios.

Fixed Interest

Accrue interest with the actual_actual accrual method starting on 2025-03-15 with a fixed 4.25% rate.

curl https://api.column.com/interests/configs
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  --data-raw '{
      "accrual_method": "actual_actual",
      "description": "simple fixed interest rate",
      "effective_date": "2025-03-15",
      "product_type": "bank_account",
      "tiers": [
        {
          "threshold": "0", 
          "fixed_rate": "0.0425"
        }
      ]
   }'

Floating Interest

Accrue interest with the actual_actual accrual method starting 2025-03-15 with a floating rate that is 90% of a 4.50% pivot rate. First, you create a pivot rate with an effective date before or on 2025-03-15:

curl https://api.column.com/interests/pivot-rates
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  -d effective_date="2025-03-01" \
  -d product_type="bank_account" \
  -d rate="0.045"

Then create an interest config with a floating interest rate using pivot_percentage:

curl https://api.column.com/interests/configs
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  --data-raw '{
      "accrual_method": "actual_actual",
      "description": "simple floating interest rate",
      "effective_date": "2025-03-15",
      "product_type": "bank_account",
      "tiers": [
        {
          "threshold": "0", 
          "pivot_percentage": "0.9"
        }
      ]
   }'

Tier-based Interest

Accrue interest with the actual_actual accrual method starting 2025-03-15 with a 4.00% ceiling rate and a 0.50% floor rate. Use tier-based interest with the following tiers: 2.00% for balances < $100K, 90% of the pivot rate for balances between $100K and $250K, and the pivot rate - 1.25% for balances above $250K:

curl https://api.column.com/interests/configs
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  --data-raw '{
      "accrual_method": "actual_actual",
      "description": "tier-based interest rate",
      "effective_date": "2025-03-15",
      "product_type": "bank_account",
      "ceiling_rate": "0.04",
      "floor_rate": "0.005",
      "tiers": [
        {
          "threshold": "0", 
          "fixed_rate": "0.02"
        },
        {
          "threshold": "10000000", 
          "pivot_percentage": "0.9"
        },
        {
          "threshold": "25000000", 
          "pivot_relative": "-0.0125"
        },
      ]
   }'

Schedule Future Interest Rates and Configs

To schedule future pivot rates such as:

  • 5.00% on or after 2025-01-01
  • 2.50% on or after 2025-07-01
curl https://api.column.com/interests/pivot-rates
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  -d effective_date="2025-01-01" \
  -d product_type="bank_account" \
  -d rate="0.05"`

curl https://api.column.com/interests/pivot-rates
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  -d effective_date="2025-07-01" \
  -d product_type="bank_account" \
  -d rate="0.025"

In addition, assume you would like to accrue interest as follows:

  • Starting 2025-03-15: use the actual_actual method with a fixed promotion rate of 5.00%
  • Starting 2025-06-15: use the actual_365 method with a ceiling rate of 4.00%, floor rate of 0.50%, and tier-based interest:
    • 2.00% for balances < $100K
    • 90% of the pivot rate for balances between $100K and $250K
    • pivot rate - 1.25% for balances above $250K
# create a new interest config: 
curl https://api.column.com/interests/configs
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  --data-raw '{
      "accrual_method": "actual_actual",
      "effective_date": "2025-03-15",
      "product_type": "bank_account",
      "tiers": [
        {
          "threshold": "0", 
          "fixed_rate": "0.05"
        }
      ]
   }'

# assume the ID created above is icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2
# update the existing interest config
curl https://api.column.com/interests/configs/icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  --data-raw '{
      "accrual_method": "actual_actual",
      "description": "tier-based interest rate",
      "effective_date": "2025-06-15",
      "ceiling_rate": "0.04",
      "floor_rate": "0.005",
      "tiers": [
        {
          "threshold": "0", 
          "fixed_rate": "0.02"
        },
        {
          "threshold": "10000000", 
          "pivot_percentage": "0.9"
        },
        {
          "threshold": "25000000", 
          "pivot_relative": "-0.0125"
        }
      ]
   }'

Query Config Details for Accrual Dates

If an interest config has multiple snapshots with different effective dates, you can pull the snapshot used on given accrual dates. Let's use the example interest config created at Schedule Future Interest Rates.

Before 2025-03-15

Since the earliest effective date of this config's snapshots is 2025-03-15, no interest is accrued before 2025-03-15. If you query the config's rate details with an accrual_date before 2025-03-15, we will return the earliest effective snapshot:

GET /interests/configs/icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2?accrual_date=2025-01-01.

{
  "accrual_method": "actual_actual",
  "ceiling_rate": null,
  "created_at": "2024-06-12T16:36:41Z",
  "description": "tier-based interest rate",
  "effective_date": "2025-03-15",
  "floor_rate": null,
  "history": null,
  "id": "icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2",
  "idempotency_key": null,
  "pivot_rate": null,
  "product_type": "bank_account",
  "tiers": [
    {
      "fixed_rate": "0.05",
      "pivot_percentage": null,
      "pivot_relative": null,
      "threshold": "0"
    }
  ],
  "updated_at": "2024-06-12T16:37:32Z"
}

Between 2025-03-15 and 2025-06-14

The fixed 5.00% rate is applied during this period:

GET /interests/configs/icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2?accrual_date=2025-03-20&expand=pivot_rate

{
  "accrual_method": "actual_actual",
  "ceiling_rate": null,
  "created_at": "2024-06-12T16:36:41Z",
  "description": "tier-based interest rate",
  "effective_date": "2025-03-15",
  "floor_rate": null,
  "history": null,
  "id": "icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2",
  "idempotency_key": null,
  "pivot_rate": {
    "created_at": "2024-06-12T16:30:54Z",
    "effective_date": "2025-01-01",
    "id": "ipvt_2hmqyKGAK6x5DWynBJNIhEBaqH3",
    "idempotency_key": null,
    "product_type": "bank_account",
    "rate": "0.05",
    "updated_at": "2024-06-12T16:30:54Z"
  },
  "product_type": "bank_account",
  "tiers": [
    {
      "fixed_rate": "0.05",
      "pivot_percentage": null,
      "pivot_relative": null,
      "threshold": "0"
    }
  ],
  "updated_at": "2024-06-12T16:37:32Z"
}

Between 2025-06-15 and 2025-06-30

The tier-based rate with a 5.00% pivot rate (capped at 4.00%, and floored at 0.50%) is applied during this period:

GET /interests/configs/icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2?accrual_date=2025-06-20&expand=pivot_rate

{
  "accrual_method": "actual_actual",
  "ceiling_rate": "0.04",
  "created_at": "2024-06-12T16:36:41Z",
  "description": "tier-based interest rate",
  "effective_date": "2025-06-15",
  "floor_rate": "0.005",
  "history": null,
  "id": "icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2",
  "idempotency_key": null,
  "pivot_rate": {
    "created_at": "2024-06-12T16:30:54Z",
    "effective_date": "2025-01-01",
    "id": "ipvt_2hmqyKGAK6x5DWynBJNIhEBaqH3",
    "idempotency_key": null,
    "product_type": "bank_account",
    "rate": "0.05",
    "updated_at": "2024-06-12T16:30:54Z"
  },
  "product_type": "bank_account",
  "tiers": [
    {
      "fixed_rate": "0.02",
      "pivot_percentage": null,
      "pivot_relative": null,
      "threshold": "0"
    },
    {
      "fixed_rate": null,
      "pivot_percentage": "0.9",
      "pivot_relative": null,
      "threshold": "10000000"
    },
    {
      "fixed_rate": null,
      "pivot_percentage": null,
      "pivot_relative": "-0.0125",
      "threshold": "25000000"
    }
  ],
  "updated_at": "2024-06-12T16:37:32Z"
}

After 2025-07-01

The tier-based rate with a 2.50% pivot rate (capped at 4.00% and floored at 0.50%) is applied during this period:

GET /interests/configs/icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2?accrual_date=2025-07-20&expand=pivot_rate

{
  "accrual_method": "actual_actual",
  "ceiling_rate": "0.04",
  "created_at": "2024-06-12T16:36:41Z",
  "description": "tier-based interest rate",
  "effective_date": "2025-06-15",
  "floor_rate": "0.005",
  "history": null,
  "id": "icfg_2hmrg8Ad91BjRSFRDfGjfatgeK2",
  "idempotency_key": null,
  "pivot_rate": {
    "created_at": "2024-06-12T16:31:14Z",
    "effective_date": "2025-07-01",
    "id": "ipvt_2hmr11iavgkjpemXnYeHhCdtEI8",
    "idempotency_key": null,
    "product_type": "bank_account",
    "rate": "0.025",
    "updated_at": "2024-06-12T16:31:14Z"
  },
  "product_type": "bank_account",
  "tiers": [
    {
      "fixed_rate": "0.02",
      "pivot_percentage": null,
      "pivot_relative": null,
      "threshold": "0"
    },
    {
      "fixed_rate": null,
      "pivot_percentage": "0.9",
      "pivot_relative": null,
      "threshold": "10000000"
    },
    {
      "fixed_rate": null,
      "pivot_percentage": null,
      "pivot_relative": "-0.0125",
      "threshold": "25000000"
    }
  ],
  "updated_at": "2024-06-12T16:37:32Z"
}