Banking API Migration Guide

Migrating from v2.0.1 to v3.0.0

Overview

This document covers all changes introduced in version 3.0.0 of the Adatree ADR Platform Open Banking API and provides guidance on what you need to update in your integration.

---

Affected API Paths

All three breaking changes (Fees, Discounts, Rate Tiers) affect a single endpoint:

Path	Operation	Response Schema	Affected Sub-Schemas
GET /adr/banking/arrangements/{cdrArrangementId}/accounts/{accountId}	getAccountDetail	ResponseBankingAccountById → BankingAccountDetail	fees[] (BankingProductFee → BankingProductDiscount), depositRates[].tiers[] (BankingProductRateTierV3), lendingRates[].tiers[] (BankingProductRateTierV3)

The other 11 paths (accounts list, balances, transactions, direct-debits, scheduled-payments, payees) do not return product fee/discount/rate tier data and are unaffected.

---

Changelog Summary

Updates

Schema	Old Structure	New Structure
BankingProductFee	Flat fields: amount, balanceRate, transactionRate, accruedRate, accrualFrequency + structured fixedAmount/rateBased/variable	Only structured fields: fixedAmount/rateBased/variable (flat fields removed)
BankingProductDiscount	Flat fields: amount, balanceRate, transactionRate, accruedRate, feeRate + structured fixedAmount/rateBased	Only structured fields: fixedAmount/rateBased (flat fields removed)
BankingProductRateTierV3	Numeric minimumValue/maximumValue + optional minimumValueString/maximumValueString; singular applicabilityConditions	String minimumValueString (required)/maximumValueString; array applicabilityConditionList (numeric bounds removed)

Removals

Schemas	Status
BankingProductFee.amount, .balanceRate, .transactionRate, .accruedRate, .accrualFrequency	Removed in v3.0.0 (were deprecated in v2.0.1)
BankingProductDiscount.amount, .balanceRate, .transactionRate, .accruedRate, .feeRate	Removed in v3.0.0 (were deprecated in v2.0.1)
BankingProductRateTierV3.minimumValue, .maximumValue, .applicabilityConditions	Removed in v3.0.0 (were deprecated in v2.0.1)

---

Breaking Changes for API Users

1. Banking Product Fees – Flat Fields Removed

Old (v2.0.1):

{
  "name": "Monthly Fee",
  "feeType": "PERIODIC",
  "amount": "15.00",
  "balanceRate": null,
  "transactionRate": null,
  "accruedRate": null,
  "accrualFrequency": null,
  "fixedAmount": {
    "amount": "15.00"
  },
  "currency": "AUD"
}

New (v3.0.0):

{
  "name": "Monthly Fee",
  "feeType": "PERIODIC",
  "fixedAmount": {
    "amount": "15.00"
  },
  "currency": "AUD"
}

Fields Removed (required migration):

• amount (deprecated)
• balanceRate (deprecated)
• transactionRate (deprecated)
• accruedRate (deprecated)
• accrualFrequency (deprecated)

Action: Consumers must update JSON parsing to read from fixedAmount.amount / rateBased.rate / variable instead of flat fields.

---

2. Banking Product Discounts – Flat Fields Removed

Old (v2.0.1):

{
  "description": "Loyalty Discount",
  "discountType": "BALANCE",
  "amount": "0.50",
  "balanceRate": null,
  "transactionRate": null,
  "accruedRate": null,
  "feeRate": null,
  "fixedAmount": {
    "amount": "0.50"
  }
}

New (v3.0.0):

{
  "description": "Loyalty Discount",
  "discountType": "BALANCE",
  "fixedAmount": {
    "amount": "0.50"
  }
}

Fields Removed (required migration):

• amount (deprecated)
• balanceRate (deprecated)
• transactionRate (deprecated)
• accruedRate (deprecated)
• feeRate (deprecated)

Action: Consumers must update JSON parsing to read from fixedAmount.amount / rateBased.rate instead of flat fields.

---

3. Banking Product Rate Tiers – Numeric Bounds Removed, String Required

Old (v2.0.1):

{
  "name": "Term 12-24 Months",
  "unitOfMeasure": "MONTH",
  "minimumValue": 12,
  "maximumValue": 24,
  "minimumValueString": "12",
  "maximumValueString": "24",
  "applicabilityConditions": {
    "rateApplicabilityType": "OTHER",
    "additionalInfo": "..."
  },
  "applicabilityConditionList": [
    {
      "rateApplicabilityType": "OTHER",
      "additionalInfo": "..."
    }
  ]
}

New (v3.0.0):

{
  "name": "Term 12-24 Months",
  "unitOfMeasure": "MONTH",
  "minimumValueString": "12",
  "maximumValueString": "24",
  "applicabilityConditionList": [
    {
      "rateApplicabilityType": "OTHER",
      "additionalInfo": "..."
    }
  ]
}

Fields Removed (required migration):

• minimumValue (numeric, deprecated)
• maximumValue (numeric, deprecated)
• applicabilityConditions (singular, deprecated)

Required Field Added:

• minimumValueString (string, required — no longer optional)

Fields Added:

• maximumValueString (string)
• applicabilityConditionList (array of conditions, replaces singular)

Action: Consumers must:

1. Change numeric parsing of tier bounds to string parsing
2. Supply minimumValueString — no longer optional
3. Update condition logic to iterate applicabilityConditionList (array) instead of reading singular applicabilityConditions

---

Migration Path

For All Consumers (SDK Regeneration Required)

1. Regenerate SDK from v3.0.0 spec
2. Update code reading deprecated flat fee/discount/tier fields → use structured objects (fixedAmount, rateBased, etc.)
3. Ensure minimumValueString is supplied for all tier bounds (required field in v3.0.0)
4. Update tier condition logic to iterate applicabilityConditionList array instead of reading singular applicabilityConditions