Obtain a list of products that are currently openly offered to the market
Note that the results returned by this end point 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 here, in one place.
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 name additionalValue. 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 difference 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 long offered can be marked not effective for a few weeks before they are then removed from the product set as an option entirely.
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'
Only include products that have been updated after the specified date and time. If absent defaults to include all products
brand
query
string
optional
Filter results based on a specific brand
product-category
query
string
optional
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.
Page size to request. Default is 25 (standard pagination)
x-v
header
string
mandatory
Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers
x-min-v
header
string
optional
Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable.
A data holder specific unique identifier for this product. This identifier must be unique to a product but does not otherwise need to adhere to ID permanence guidelines.
The date and time from which this product is effective (ie. is available for origination). Used to enable the articulation of products to the regime before they are available for customers to originate
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
URI reference to a PNG, JPG or GIF image with proportions defined by ISO 7810 ID-1 and width no greater than 512 pixels. The URI reference may be a link or url-encoded data URI according to [RFC2397]
Description of fees, pricing, discounts, exemptions and bonuses for the product. Mandatory if additionalFeesAndPricingUris includes one or more supporting documents.
An array of additional general overviews for the product or features of the product, if applicable. To be treated as secondary documents to the overviewUri. Only to be used if there is a primary overviewUri.
An array of additional terms and conditions for the product, if applicable. To be treated as secondary documents to the termsUri. Only to be used if there is a primary termsUri.
An array of additional eligibility rules and criteria for the product, if applicable. To be treated as secondary documents to the eligibilityUri. Only to be used if there is a primary eligibilityUri.
An array of additional fees, pricing, discounts, exemptions and bonuses for the product, if applicable. To be treated as secondary documents to the feesAndPricingUri. Only to be used if there is a primary feesAndPricingUri.
An array of additional bundles for the product, if applicable. To be treated as secondary documents to the bundleUri. Only to be used if there is a primary bundleUri.
Link to a web page with more information on the bundle criteria and benefits
productIds
[string]
optional
Array of product IDs for products included in the bundle that are available via the product end points. 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 end points
Generic field containing additional information relevant to the featureType specified. Whether mandatory or not is dependent on the value of the featureType.
additionalInfo
string
conditional
Display text providing more information on the feature. Mandatory if the feature type is set to OTHER
The type of constraint described. See the next section for an overview of valid values and their meaning
additionalValue
string
conditional
Generic field containing additional information relevant to the constraintType specified. Whether mandatory or not is dependent on the value of constraintType
additionalInfo
string
optional
Display text providing more information the constraint
The type of eligibility criteria described. See the next section for an overview of valid values and their meaning
additionalValue
string
conditional
Generic field containing additional information relevant to the eligibilityType specified. Whether mandatory or not is dependent on the value of eligibilityType
additionalInfo
string
conditional
Display text providing more information on the eligibility criteria. Mandatory if the field is set to OTHER
A fee rate calculated based on a proportion of the balance. One of amount, balanceRate, transactionRate and accruedRate is mandatory unless the feeType "VARIABLE" is supplied.
A fee rate calculated based on a proportion of a transaction. One of amount, balanceRate, transactionRate and accruedRate is mandatory unless the feeType "VARIABLE" is supplied
A fee rate calculated based on a proportion of the calculated interest accrued on the account. One of amount, balanceRate, transactionRate and accruedRate is mandatory unless the feeType "VARIABLE" is supplied
The indicative frequency with which the fee is calculated on the account. Only applies if balanceRate or accruedRate is also present. Formatted according to ISO 8601 Durations (excludes recurrence syntax)
A discount rate calculated based on a proportion of the balance. Note that the currency of the fee discount is expected to be the same as the currency of the fee itself. One of amount, balanceRate, transactionRate, accruedRate and feeRate is mandatory. Unless noted in additionalInfo, assumes the application and calculation frequency are the same as the corresponding fee
A discount rate calculated based on a proportion of a transaction. Note that the currency of the fee discount is expected to be the same as the currency of the fee itself. One of amount, balanceRate, transactionRate, accruedRate and feeRate is mandatory
A discount rate calculated based on a proportion of the calculated interest accrued on the account. Note that the currency of the fee discount is expected to be the same as the currency of the fee itself. One of amount, balanceRate, transactionRate, accruedRate and feeRate is mandatory. Unless noted in additionalInfo, assumes the application and calculation frequency are the same as the corresponding fee
A discount rate calculated based on a proportion of the fee to which this discount is attached. Note that the currency of the fee discount is expected to be the same as the currency of the fee itself. One of amount, balanceRate, transactionRate, accruedRate and feeRate is mandatory. Unless noted in additionalInfo, assumes the application and calculation frequency are the same as the corresponding fee
additionalValue
string
conditional
Generic field containing additional information relevant to the discountType specified. Whether mandatory or not is dependent on the value of discountType
additionalInfo
string
optional
Display text providing more information on the discount
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.
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.
» title
string
mandatory
A short, human-readable summary of the problem that MUST NOT change from occurrence to occurrence of the problem represented by the error code.
» detail
string
mandatory
A human-readable explanation specific to this occurrence of the problem.
