Bank of Sydney Banking Products API
Banking Product endpoints
Banking Product endpoints
openapi: 3.0.3
info:
contact:
email: contact@dsb.gov.au
name: Data Standards Body
url: https://dsb.gov.au/
description: Specifications for resource endpoints applicable to data holders in the Banking sector.
license:
name: MIT License
url: https://opensource.org/licenses/MIT
title: CDR Banking Banking Account Balances Banking Products API
version: 1.36.0
servers:
- description: MTLS
url: https://mtls.dh.example.com/cds-au/v1
tags:
- description: Banking Product endpoints
name: Banking Products
x-shortName: Products
paths:
/banking/products:
get:
description: 'Obtain a list of products that are currently openly offered to the market.
Note that the results returned by this endpoint are expected to be ordered in descending order according to _lastUpdated_.
### Conventions
In the product reference payloads there are a number of recurring conventions that are explained below.
#### Arrays Of Features
In the product detail payload there are a number of arrays articulating generic features, constraints, prices, etc. The intent of these arrays is as follows:
- Each element in an array has the same structure so that clients can reliably interpret the payloads
- Each element as a type element that is an enumeration of the specific aspect of a product being described, such as types of fees.
- Each element has a field named [_additionalValue_](#productfeaturetypedoc). This is a generic field with contents that will vary based on the type of object being described. The contents of this field for the `ADDITIONAL_CARDS` feature is the number of cards allowed while the contents of this field for the `MAX_LIMIT` constraint would be the maximum credit limit allowed for the product.
- An element in these arrays of the same type may appear more than once. For instance, a product may offer two separate loyalty programs that the customer can select from. A fixed term mortgage may have different rates for different term lengths.
- An element in these arrays may contain an _additionalInfo_ and _additionalInfoUri_ field. The _additionalInfo_ field is used to provide displayable text clarifying the purpose of the element in some way when the product is presented to a customer. The _additionalInfoUri_ provides a link to externally hosted information specifically relevant to that feature of the product.
- Depending on the type of data being represented there may be additional specific fields.
#### URIs To More Information
As the complexities and nuances of a financial product can not easily be fully expressed in a data structure without a high degree of complexity it is necessary to provide additional reference information that a potential customer can access so that they are fully informed of the features and implications of the product. The payloads for product reference therefore contain numerous fields that are provided to allow the product holder to describe the product more fully using a web page hosted on their online channels.
These URIs do not need to all link to different pages. If desired, they can all link to a single hosted page and use different HTML anchors to focus on a specific topic such as eligibility or fees.
#### Linkage To Accounts
From the moment that a customer applies for a product and an account is created the account and the product that spawned it will diverge. Rates and features of the product may change and a discount may be negotiated for the account.
For this reason, while _productCategory_ is a common field between accounts and products, there is no specific ID that can be used to link an account to a product within the regime.
Similarly, many of the fields and objects in the product payload will appear in the account detail payload but the structures and semantics are not identical as one refers to a product that can potentially be originated and one refers to an account that actually has been instantiated and created along with the associated decisions inherent in that process.
#### Dates
It is expected that data consumers needing this data will call relatively frequently to ensure the data they have is representative of the current offering from a bank. To minimise the volume and frequency of these calls the ability to set a _lastUpdated_ field with the date and time of the last update to this product is included. A call for a list of products can then be filtered to only return products that have been updated since the last time that data was obtained using the _updated-since_ query parameter.
In addition, the concept of effective date and time has also been included. This allows for a product to be marked for obsolescence, or introduction, from a certain time without the need for an update to show that a product has been changed. The inclusion of these dates also removes the need to represent deleted products in the payload. Products that are no longer offered can be marked not effective for a few weeks before they are then removed from the product set as an option entirely.
Obsolete versions: [v1](includes/obsolete/get-products-v1.html), [v2](includes/obsolete/get-products-v2.html), [v3](includes/obsolete/get-products-v3.html), [v4](includes/obsolete/get-products-v4.html).'
operationId: listBankingProducts
parameters:
- description: Allows for the filtering of products based on whether the current time is within the period of time defined as effective by the _effectiveFrom_ and _effectiveTo_ fields. Valid values are `CURRENT`, `FUTURE` and `ALL`. If absent defaults to `CURRENT`.
explode: true
in: query
name: effective
required: false
schema:
default: CURRENT
enum:
- ALL
- CURRENT
- FUTURE
type: string
style: form
- description: Only include products that have been updated after the specified date and time. If absent defaults to include all products.
explode: true
in: query
name: updated-since
required: false
schema:
type: string
style: form
x-cds-type: DateTimeString
- description: Filter results based on a specific brand.
explode: true
in: query
name: brand
required: false
schema:
type: string
style: form
- description: Used to filter results on the _productCategory_ field applicable to accounts. Any one of the valid values for this field can be supplied. If absent then all accounts returned.
explode: true
in: query
name: product-category
required: false
schema:
$ref: '#/components/schemas/BankingProductCategoryV2'
style: form
- description: Page of results to request (standard pagination).
explode: true
in: query
name: page
required: false
schema:
default: 1
type: integer
style: form
x-cds-type: PositiveInteger
- description: Page size to request. Default is 25 (standard pagination).
explode: true
in: query
name: page-size
required: false
schema:
default: 25
type: integer
style: form
x-cds-type: PositiveInteger
- description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
explode: false
in: header
name: x-v
required: true
schema:
type: string
style: simple
- description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
explode: false
in: header
name: x-min-v
required: false
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseBankingProductListV4'
description: Successful response
headers:
x-v:
$ref: '#/components/headers/XV'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseErrorListV2'
description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Missing Required Header](#error-400-header-missing)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li><li>[400 - Invalid Date](#error-400-field-invalid-date-time)</li><li>[400 - Invalid Page Size](#error-400-field-invalid-page-size)</li></ul>
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseErrorListV2'
description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseErrorListV2'
description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[422 - Invalid Page](#error-422-field-invalid-page)</li></ul>
servers:
- description: TLS
url: https://tls.dh.example.com/cds-au/v1
summary: Get Products
tags:
- Banking Products
x-version: '5'
/banking/products/{productId}:
get:
description: 'Obtain detailed information on a single product offered openly to the market.
Obsolete versions: [v1](includes/obsolete/get-product-detail-v1.html), [v2](includes/obsolete/get-product-detail-v2.html), [v3](includes/obsolete/get-product-detail-v3.html), [v4](includes/obsolete/get-product-detail-v4.html), [v5](includes/obsolete/get-product-detail-v5.html), [v6](includes/obsolete/get-product-detail-v6.html).'
operationId: getBankingProductDetail
parameters:
- description: The _productId_ to obtain data for. _productId_ values are returned by product list endpoints.
explode: false
in: path
name: productId
required: true
schema:
$ref: '#/components/schemas/BankingProductId'
style: simple
x-cds-type: ASCIIString
- description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
explode: false
in: header
name: x-v
required: true
schema:
type: string
style: simple
- description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
explode: false
in: header
name: x-min-v
required: false
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseBankingProductByIdV7'
description: Successful response
headers:
x-v:
$ref: '#/components/headers/XV'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseErrorListV2'
description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Missing Required Header](#error-400-header-missing)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li></ul>
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseErrorListV2'
description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[404 - Unavailable Resource](#error-404-resource-unavailable)</li><li>[404 - Invalid Resource](#error-404-resource-invalid)</li></ul>
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseErrorListV2'
description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
servers:
- description: TLS
url: https://tls.dh.example.com/cds-au/v1
summary: Get Product Detail
tags:
- Banking Products
x-version: '7'
components:
schemas:
BankingProductAdditionalInformationV2_additionalInformationUris:
properties:
description:
description: Display text providing more information about the document URI.
type: string
additionalInfoUri:
description: The URI describing the additional information.
type: string
x-cds-type: URIString
required:
- additionalInfoUri
type: object
BankingProductDiscountV2:
description: Note that the currency of the fee discount is expected to be the same as the currency of the fee itself.
properties:
description:
description: Description of the discount.
type: string
discountType:
description: The type of discount. For further details, refer to [Product Discount Types](#tocSproductdiscounttypedoc).
enum:
- BALANCE
- DEPOSITS
- ELIGIBILITY_ONLY
- FEE_CAP
- PAYMENTS
type: string
discountMethodUType:
description: Reference to the applicable fee discount method structure.
enum:
- fixedAmount
- rateBased
type: string
fixedAmount:
allOf:
- $ref: '#/components/schemas/BankingFeeDiscountAmount'
description: Mandatory if the _discountMethodUType_ value is `fixedAmount`. Where the discount is a specific amount.
rateBased:
allOf:
- $ref: '#/components/schemas/BankingFeeDiscountRate'
description: Mandatory if the _discountMethodUType_ value is `rateBased`. Where the discount is based on a type of rate. Unless noted in _additionalInfo_, assumes the application and calculation frequency are the same as the corresponding fee.
additionalValue:
description: Generic field containing additional information relevant to the [_discountType_](#tocSproductdiscounttypedoc) specified. Whether mandatory or not is dependent on the value of [_discountType_](#tocSproductdiscounttypedoc).
type: string
additionalInfo:
description: Display text providing more information on the discount.
type: string
additionalInfoUri:
description: Link to a web page with more information on this discount.
type: string
x-cds-type: URIString
eligibility:
description: Eligibility constraints that apply to this discount. Mandatory if the [_discountType_](#tocSproductdiscounttypedoc) value is `ELIGIBILITY_ONLY`.
items:
$ref: '#/components/schemas/BankingProductDiscountEligibility'
type: array
required:
- description
- discountMethodUType
- discountType
type: object
x-conditional:
- fixedAmount
- rateBased
- additionalValue
- eligibility
Meta:
type: object
BankingProductDetailV7_allOf:
properties:
bundles:
description: An array of bundles that this product participates in. Each bundle is described by free form information but also by a list of _productID_ values of the other products that are included in the bundle. It is assumed that the current product is included in the bundle also.
items:
$ref: '#/components/schemas/BankingProductBundle'
type: array
features:
description: Array of features and limitations of the product.
items:
$ref: '#/components/schemas/BankingProductFeatureV4'
type: array
constraints:
description: Constraints on the application for the product such as minimum balances or limit thresholds.
items:
$ref: '#/components/schemas/BankingProductConstraintV3'
type: array
eligibility:
description: Eligibility criteria for the product.
items:
$ref: '#/components/schemas/BankingProductEligibilityV2'
type: array
fees:
description: Fees applicable to the product.
items:
$ref: '#/components/schemas/BankingProductFeeV2'
type: array
depositRates:
description: Interest rates available for deposits.
items:
$ref: '#/components/schemas/BankingProductDepositRateV2'
type: array
lendingRates:
description: Interest rates charged against lending balances.
items:
$ref: '#/components/schemas/BankingProductLendingRateV3'
type: array
instalments:
$ref: '#/components/schemas/BankingProductInstalments'
type: object
ResponseBankingProductByIdV7:
properties:
data:
$ref: '#/components/schemas/BankingProductDetailV7'
links:
$ref: '#/components/schemas/Links'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- links
type: object
ErrorV2:
properties:
code:
description: The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the _meta_ object. Otherwise, the value is the error code URN.
type: string
title:
description: A short, human-readable summary of the problem that **MUST NOT** change from occurrence to occurrence of the problem represented by the error code.
type: string
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
meta:
$ref: '#/components/schemas/ErrorV2_meta'
required:
- code
- detail
- title
type: object
x-conditional:
- meta
BankingProductDetailV7:
allOf:
- $ref: '#/components/schemas/BankingProductV6'
- $ref: '#/components/schemas/BankingProductDetailV7_allOf'
BankingFeeDiscountRate:
properties:
rateType:
description: Type of fee rate discount calculation.<ul><li>`BALANCE` A fee rate discount based on a balance</li><li>`FEE` A fee rate discount based on the fee to which the discount is attached</li><li>`INTEREST_ACCRUED` A fee rate discount based on interest accrued</li><li>`TRANSACTION` A fee rate discount based on a transaction.</li></ul>
enum:
- BALANCE
- FEE
- INTEREST_ACCRUED
- TRANSACTION
type: string
rate:
description: The fee rate discount calculated according to the _rateType_.
type: string
x-cds-type: RateString
amountRange:
$ref: '#/components/schemas/BankingFeeDiscountRange'
required:
- rate
- rateType
type: object
BankingFeeRate:
properties:
rateType:
description: Type of fee rate calculation.<ul><li>`BALANCE` A fee rate based on a balance</li><li>`INTEREST_ACCRUED` A fee rate based on interest accrued</li><li>`TRANSACTION` A fee rate based on a transaction.</li></ul>
enum:
- BALANCE
- INTEREST_ACCRUED
- TRANSACTION
type: string
rate:
description: The fee rate calculated according to the _rateType_.
type: string
x-cds-type: RateString
accrualFrequency:
description: The indicative frequency with which the fee is calculated on the account if applicable. Formatted according to [ISO 8601 Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) (excludes recurrence syntax).
type: string
x-cds-type: ExternalRef
amountRange:
$ref: '#/components/schemas/BankingFeeRange'
required:
- rate
- rateType
type: object
x-conditional:
- balanceRate
- transactionRate
- accruedRate
BankingFeeRange:
description: A minimum or maximum fee amount where a specific fixed amount is not known until the fee is incurred.
properties:
feeMinimum:
description: The minimum fee that will be charged per occurrence.
type: string
x-cds-type: AmountString
feeMaximum:
description: The maximum fee that will be charged per occurrence.
type: string
x-cds-type: AmountString
type: object
Links:
properties:
self:
description: Fully qualified link that generated the current response document.
type: string
x-cds-type: URIString
required:
- self
type: object
BankingFeeDiscountAmount:
properties:
amount:
description: The specific amount discounted from the fee each time it is incurred.
type: string
x-cds-type: AmountString
required:
- amount
type: object
BankingProductBundle:
properties:
name:
description: Name of the bundle.
type: string
description:
description: Description of the bundle.
type: string
additionalInfo:
description: Display text providing more information on the bundle.
type: string
additionalInfoUri:
description: Link to a web page with more information on the bundle criteria and benefits.
type: string
x-cds-type: URIString
productIds:
description: Array of _productID_ values for products included in the bundle that are available via the product endpoints. Note that this array is not intended to represent a comprehensive model of the products included in the bundle and some products available for the bundle may not be available via the product reference endpoints.
items:
$ref: '#/components/schemas/BankingProductId'
type: array
required:
- description
- name
type: object
ResponseBankingProductListV4:
properties:
data:
$ref: '#/components/schemas/ResponseBankingProductListV4_data'
links:
$ref: '#/components/schemas/LinksPaginated'
meta:
$ref: '#/components/schemas/MetaPaginated'
required:
- data
- links
- meta
type: object
ResponseBankingProductListV4_data:
properties:
products:
description: The list of products returned. If the filter results in an empty set then this array may have no records.
items:
$ref: '#/components/schemas/BankingProductV6'
type: array
required:
- products
type: object
BankingFeeAmount:
properties:
amount:
description: The specific amount charged for the fee each time it is incurred.
type: string
x-cds-type: AmountString
required:
- amount
type: object
MetaPaginated:
properties:
totalRecords:
description: The total number of records in the full set. See [pagination](#pagination).
type: integer
x-cds-type: NaturalNumber
totalPages:
description: The total number of pages in the full set. See [pagination](#pagination).
type: integer
x-cds-type: NaturalNumber
required:
- totalPages
- totalRecords
type: object
BankingProductV6:
properties:
productId:
$ref: '#/components/schemas/BankingProductId'
effectiveFrom:
description: The date and time from which this product is effective (i.e. is available for origination). Used to enable the articulation of products to the regime before they are available for customers to originate.
type: string
x-cds-type: DateTimeString
effectiveTo:
description: The date and time at which this product will be retired and will no longer be offered. Used to enable the managed deprecation of products.
type: string
x-cds-type: DateTimeString
lastUpdated:
description: The last date and time that the information for this product was changed (or the creation date for the product if it has never been altered).
type: string
x-cds-type: DateTimeString
productCategory:
$ref: '#/components/schemas/BankingProductCategoryV2'
name:
description: The display name of the product.
type: string
description:
description: A description of the product.
type: string
brand:
description: A label of the brand for the product. Able to be used for filtering. For data holders with single brands this value is still required.
type: string
brandName:
description: An optional display name of the brand.
type: string
brandGroup:
description: The *brandGroup* of a consumer data sharing brand that the product is associated with.
type: string
x-cds-type: ASCIIString
applicationUri:
description: A link to an application web page where this product can be applied for.
type: string
x-cds-type: URIString
isTailored:
description: Indicates whether the product is specifically tailored to a circumstance. In this case fees and prices are significantly negotiated depending on context. While all products are open to a degree of tailoring this flag indicates that tailoring is expected and thus that the provision of specific fees and rates is not applicable.
type: boolean
additionalInformation:
$ref: '#/components/schemas/BankingProductAdditionalInformationV2'
cardArt:
description: Information about any cards available with the account.
items:
$ref: '#/components/schemas/BankingProductCardArt'
type: array
required:
- brand
- description
- isTailored
- lastUpdated
- name
- productCategory
- productId
type: object
BankingProductDiscountEligibility:
properties:
discountEligibilityType:
description: The type of the specific eligibility constraint for a discount. For further details, refer to [Product Discount Eligibility Types](#tocSproductdiscounteligibilitydoc).
enum:
- BUSINESS
- EMPLOYMENT_STATUS
- INTRODUCTORY
- MAX_AGE
- MIN_AGE
- MIN_INCOME
- MIN_TURNOVER
- NATURAL_PERSON
- OTHER
- PENSION_RECIPIENT
- RESIDENCY_STATUS
- STAFF
- STUDENT
type: string
additionalValue:
description: Generic field containing additional information relevant to the [_discountEligibilityType_](#tocSproductdiscounteligibilitydoc) specified. Whether mandatory or not is dependent on the value of [_discountEligibilityType_](#tocSproductdiscounteligibilitydoc).
type: string
additionalInfo:
description: Display text providing more information on this eligibility constraint. Mandatory if the [_discountEligibilityType_](#tocSproductdiscounteligibilitydoc) value is `OTHER`.
type: string
additionalInfoUri:
description: Link to a web page with more information on this eligibility constraint.
type: string
x-cds-type: URIString
required:
- discountEligibilityType
type: object
x-conditional:
- additionalInfo
- additionalValue
ResponseErrorListV2:
properties:
errors:
description: List of errors.
items:
$ref: '#/components/schemas/ErrorV2'
type: array
required:
- errors
type: object
ErrorV2_meta:
description: Additional data for customised error codes.
properties:
urn:
description: The CDR error code URN which the application-specific error code extends. Mandatory if the error _code_ is an application-specific error rather than a standardised error code.
type: string
type: object
x-conditional:
- urn
LinksPaginated:
properties:
self:
description: Fully qualified link that generated the current response document.
type: string
x-cds-type: URIString
first:
description: URI to the first page of this set. Mandatory if this response is not the first page.
type: string
x-cds-type: URIString
prev:
description: URI to the previous page of this set. Mandatory if this response is not the first page.
type: string
x-cds-type: URIString
next:
description: URI to the next page of this set. Mandatory if this response is not the last page.
type: string
x-cds-type: URIString
last:
description: URI to the last page of this set. Mandatory if this response is not the last page.
type: string
x-cds-type: URIString
required:
- self
type: object
x-conditional:
- prev
- next
- first
- last
BankingProductAdditionalInformationV2:
description: Object that contains links to additional information on specific topics.
properties:
overviewUri:
description: General overview of the product. Mandatory if _additionalOverviewUris_ includes one or more supporting documents.
type: string
x-cds-type: URIString
termsUri:
description: Terms and conditions for the product. Mandatory if _additionalTermsUris_ includes one or more supporting documents.
type: string
x-cds-type: URIString
eligibilityUri:
description: Eligibility rules and criteria for the product. Mandatory if _additionalEligibilityUris_ includes one or more supporting documents.
type: string
x-cds-type: URIString
feesAndPricingUri:
description: Description of fees, pricing, discounts, exemptions and bonuses for the product. Mandatory if _additionalFeesAndPricingUris_ includes one or more supporting documents.
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bank-of-sydney/refs/heads/main/openapi/bank-of-sydney-banking-products-api-openapi.yml