Decision Proposal 027 - Basic Account Payloads

[JamesMBligh]

This decision proposal outlines a recommendation for payloads of the Basic Account end points and Balance specific end points.

Feedback is now open for this proposal. Feedback is planned to be closed on the 19th October. Due to the complexity of the data payloads, a revised version will be published around the 13th October incorporating feedback received to that date. Decision Proposal 027 - Basic Account Payloads.pdf

[JamesMBligh]

Thanks to all that spotted my deliberate mistake in the title of the proposal document. I've fixed it now :)

-JB-

[deboraelkin2]

A few observations:

• open-status is a query parameter for both Account List Data and Multiple Balances Data. I think open-status should be included as part of the response payload for each account, especially since the default value for the query parameter is ALL.

• How would the balance for a transactional account with an overdraft facility be represented? I think the Credit Balance type would be closest, but the name of the element loanBalance can be misleading. I'm struggling to come up with a more appropriate element name, though. Perhaps accountBalance?

• I would remove the empty meta object in the request for POST /banking/accounts/balances. It would only make sense if the endpoint supported pagination.

• Also, there are a few very minor typos and errors that would be easier to highlight in a shared document than try to include as a comment here. I'll only do it for the first one. The first paragraph should read "The end points for account data were previously proposed under decision proposal 15"

[WestpacOpenBanking]

Westpac supports the proposal with the following remarks and questions:

• Inclusion of a filter on open-status seems to imply that we need to return details on closed accounts. This is inconsistent with our online channels and including them adds implementation complexity. Suggest updating the description of the GET /banking/accounts to “Obtain a list of accounts visible in online channel associated with the consent” or similar if the intention is for consistency with what is displayed in online channels.
• There is no way to determine the open/closed status of an account without repeated queries using the open-status parameter. An openStatus field should be added.
• An “as of datetime” for balances would be a useful addition for data consumers.
• Credit/Debit balance types appear to be from the institution’s point of view. This may be confusing and clarifying text should be included in any event.
• An indication of the appropriate sign of credits and debits would help to ensure implementation consistency.
• Is the balance type determined from the product or the state of the account? What is the intended behaviour when the available balance is negative and current balance is positive or vice versa (consumer’s point of view)? Which balance type should be returned? What should be returned in the case of an account with a “flipped” balance, for instance where a transaction account becomes overdrawn or a loan is overpaid? Should the balance type change from debit to credit or vice versa or should a negative balance be held?
• The facilityLimit fieldname may not be the best choice – a group of accounts can belong to a facility and the facility limit would be a combined limit across the accounts in that case. A group of facilities as in the example may also have a combined credit limit independent of any individual facility limit. These scenarios usually appear in a business banking context. Suggest creditLimit or similar.
• If the response is empty because of the filter conditions should an empty collection be returned or e.g. HTTP 204: No content?
• Typographic error: Some of the Balance Types have { and } to be of string type. :relaxed:
• displayName is nickname OR a display name. An institution may feasibly have both available. It may be better to separate them as conditional fields where at least one must be populated.
• What is the intended use of the providerType field? Is this a provider categorisation of products? Some providers may have a hierarchy of product types if this is the intent.
• The UK read/write standard includes other balance types which may be relevant in some context.
• It should be clearly indicated that all query parameters are optional.

[bazzat]

The ABA Open Banking Technical WG has a few initial observations/questions, posted here in the hope they'll be useful in producing the revised version:

• currentBalance may need a more rigorous definition. It's not clear that the balance returned via an ATM enquiry and that returned via Internet Banking are necessarily and always the same value.
• One member’s interpretation of Current balance - is balance of the account based on settled transactions at the timestamp provided.
• availableBalance is another term that may need more rigorous definition. Though perhaps "it means whatever the lender considers it to mean" is sufficient (for both available and current balances)?
• One member’s interpretation of Available balance - The available balance is the amount of funds in which you have in your account that you are able to spend at the timestamp provided. The available balance is the current balance less any amounts that are on hold (transactions pending e.g. credit card purchases or uncleared cheque deposits).
• A suggestion/recommendation from one member is that balance data (of any type), include a timestamp field. This provides for data providers to implement real-time balances where possible, and latent balances where not technically possible - the correlation of the API call time and the balance timestamp being the indicator of the currency of the data. This would be more consistent with the UK standard that achieved similar using "balance types".
• facilityLimit may be poorly named. A facility limit and an account limit are not necessarily the same thing - a facility limit can aggregate limits across multiple accounts.
• It would be useful to have some use cases for the Multi Currency Purses Type. We’re not sure how it will be used?
• maskedNumber - Is there a specific standard for masking that is being applied here? If so can it be explicitly referenced?
• accountCategory - It might be sensible to include an OTHER in the value list. In fact the whole list probably needs to be considered much more carefully. It is likely that most banks will need a more granular list in order to map at a level of detail that is useful for product comparison purposes.

[benkolera]

A technical quip. There are a few endpoints that take query params but also are specified to never return an error. On the following endpoint, I'd assume that there would be a 400 returned on invalid filter values, pages that weren't natural numbers, etc. Is this a C&P error or would you expect the API to ignore invalid values as though they weren't supplied? That would make difficulties for developers who use a framework that validates the query params in a strong way and also create confusion when filters from a buggy consumer got dropped silently and would not be advisable.

[JamesMBligh]

@benkolera, when I state in the specs that there is no specific error expected what is meant is that there is not going to be a set of errors objects defined in the spec for the end point. It is not meant to imply that there are zero circumstances where a 400 or 422 could never be returned. I'll clean my language up in future :)

-JB-

[JamesMBligh]

Thanks for the comments. Here are responses to the feedback provided:

Open/Closed Status Closed accounts have been included as they were specifically requested by the FinTech community during initial consultation and would appear to align with the designation instrument mandate. The absence of the openStatus field in the payload was an oversight. Apologies.

Balances

• Datestamp for balances - It is implied by the currentBalance field that this is best understanding of balance right now and, as stated, it should align with the balance presented in other channels. As such the implication that it is the balance presented at the time of request is the implied standard here.
• Representing Overdraft - I will have to consider this and will include a treatment in the updated version
• Curley Braces - Again, I will fix my deliberate mistake ;)
• facilityLimit - I will rename to creditLimit
• CR/DR - I have done credit/debit from the institution perspective as they are providing the data. It doesn't really matter as long as we are consistent but I'll add a comment
• Purses - The use case for purses is Travel Cards which are offered by at least two of the majors

meta Object The payloads decision indicated this object as mandatory based on the UK spec and JSONAPI.org recommendations. That's why it is mandatory here even if it is empty.

Empty Result Set I would expect an empty result set to be indicated by an empty array rather than a 204 return code.

Nickname vs DisplayName I'll add nickName as an optional field

Account Masking We defined a PCIString primitive for PAN masking. I will add an additional for account number masking.

Hopefully these updates will be applied this evening.

One final note: please give me feedback on the accountCategory field values. It is critical that we get the content of this field correct and I don't believe the current value set is anywhere close to being correct.

-JB-

[JamesMBligh]

Please find attached version 2 of the proposal with feedback incorporated: Decision Proposal 027 - Basic Account Payloads.pdf

-JB-

[elsamarkula]

Feedback from the Australian Retail Credit Association: See ARCA’s comments in respect to the Customer Payloads discussion thread. ARCA’s observations are based in part on ARCA’s experience as owner of the Australian Credit Reporting Data Standard (ACRDS) (data input standard for credit information), as well as ARCA’s role as drafter of the Privacy (Credit Reporting) Code (CR Code). • Credit balance type – credit Limit – maximum amount of credit available. Note this should align with approach taken in CR Code paragraph 6.2(b) (which requires updating of limit for accounts subject to amortised payment schedule). Alternatively, allowance should be made for both initial credit limit and amortised limit. • Response payloads – Account ID – note ACRDS also has concept of Account ID (contained in section 5.9 of the ACRDS) – would be good if this were replicated for OB exchange, so the same Account ID were used for both credit reporting and open banking. • For Account Id need to be mindful that Accounts numbers are not always unique within an entity such as a Credit Provider – only unique within a portfolio. A CP may generate a unique Account Id which is ok for this purpose. Additionally they should provision for Account Number and BSB which is how the Account is commonly recognised. • Response payloads - Masked Number – note truncation requirements in CR Code (first 6 and last 4 digits of the account number where the account is a credit card or debit card account). • Response payloads – Account Category. Additional credit account categories in ACRDS: Auto Loan, Charge Card, Overdraft, Personal Loan (fixed term), Personal Loan (revolving), Equipment Hire or Rental. [Also have Telecommunications Services and Utilities, as well as an ‘AO’ All Other Account Types as a catch all]. Also consider inclusion of ‘written off/delinquent loan’ into Account Category – these are credit card or personal loans that have reached 180 days past due and have been transferred to a separate recoveries system, where the structure of the account will no longer reflect the original account.

[da-banking]

Inclusion of closed accounts A straightforward reading of the ACCC's Draft Rules Framework shows former customers to be in scope, so the inclusion of CLOSED accounts seems to be inevitable given that all accounts of a former customer will be CLOSED. We agree with @WestpacOpenBanking that it would be unusual to display these accounts in Internet Banking, but it seems they should be available under Open Banking, though the more common use case would be for data consumers to request accounts that were OPEN. CLOSED accounts will always have a balance of $0, but there may be transaction history related to those accounts that is of interest.

Product data Section 5.3.1. Customer data of the ACCC Draft Rules Framework states:

The ACCC also proposes to make rules to the effect that the product data specified in section 5.3.3 [Product data], as it relates to an account or accounts that a customer holds, is within scope.

We have understood this to mean that it will be possible to relate an account to a currently offered product or a former product. We would expect this data to be in the account payload - or will this be considered as part of #31?

Debit Balance, Credit Balance, and Multi Currency Purses Types It may be worthwhile to include some examples that illustrate how data should be placed into the specified data structures.

We would support the suggestions made by others that there needs to be clarity around the inclusion of negative/positive amounts versus Debit/Credit Balances.

POST /banking/accounts/balances HTTP Response Code: 422 Unprocessable Entity

Minor query: is the intention that we return "code": "0001 – Account not able to be found" or "code": "0001"? The term code seems inappropriate for a code and description.

We have been giving some thought to the implications of this error mechanism.

Suppose we have a data consumer that is periodically requesting a balance refresh to 3 accounts on behalf of a PSU. So something like:

POST /banking/accounts/balances HTTP/1.1
Host: foo.com.au
Content-Type: application/json
Content-Length: 92
{
    "data": {
        "accountIds": [
            "acc1",
            "acc2",
            "acc3"
        ]
    }
    "meta": {}
}

Supposing the PSU had a joint account relationship with "acc3", and this relationship was later removed by the primary account owner, for example a married couple may have got divorced and separated their finances.

In this scenario, the data provider would immediately stop showing this account to the PSU in Internet Banking as they no longer had any relationship to it. It seems to follow that the data provider would also not want to show this account to a data consumer under Open Banking that the PSU had previously shared it with when they had the authority to do so.

If the data consumer was sending the request above, and they started to get the error "0001 – Account not able to be found", then they would also not be getting a balance for "acc1" and "acc2", which they still have access to.

It seems that it would be simpler to deal with this kind of issue if the POST /banking/accounts/balances operation always returned balances for the accounts it could. It would include at most accounts the data consumer had specified, but the data provider would omit accounts that it could not return for such reasons.

The data consumer would update all of the balances it had received, and could purge the stale "acc3" data once the data was no longer serving the purpose it was collected for.

This seems preferable to the 422 error. To recover from this error a data consumer would need to detect the error while calling POST /banking/accounts/balances and then kick off a custom routine to GET /banking/accounts, compare the list of accounts that came back with the stored accounts, then purge "acc3", and then return to the periodic POST /banking/accounts/balances mechanism with the reduced list of accountIds which should no longer error.

Should there be an Account Sub-Category or Sub-Type? You could broadly separate accounts into DEPOSIT and LOAN products. However the distinction is blurred when it comes to things like deposit products that include overdrafts. We would recommend no sub-categories.

[NationalAustraliaBank]

NAB is broadly supportive of this proposal, with the following feedback:

Account Balances: The way balances are represented in this payload may be confusing. We propose that account balance data could be provided consistently from the perspective of the consumer so CR is a positive balance, and DR is a negative balance. In this way the sub-typing presented below could be avoided based off of the balanceType attribute.

(Below is an approximation of how we currently interpret the Current Proposal).

{
  "data": {
    "accounts": [
      {
        "accountid": "string",
        "displayName": "string",
        "maskedNumber": "string",
        "accountCategory": "SAVINGS",
        "providerType": "string",
        "balance$type": "debit",
        "debit": {
          "currentBalance": {
            "currency": "string",
            "amount": "string"
          },
          "availableBalance": {
            "currency": "string",
            "amount": "string"
          }
        },
        "credit": {
          "accountBalance": {
            "currency": "string",
            "amount": "string"
          },
          "availableBalance": {
            "currency": "string",
            "amount": "string"
          },
          "creditLimit": {
            "currency": "string",
            "amount": "string"
          }
        },
        "purses": [
          {
            "currency": "string",
            "amount": "string"
          }
        ],
        "nickname": "string"
      }
    ]
  },
  "links": {
    "self": "string",
    "first": "string",
    "prev": "string",
    "next": "string",
    "last": "string"
  },
  "meta": {
    "totalRecords": 0,
    "totalPages": 0
  }
}

Trying to have a CR & DR type defined separately is overly complicated as most accounts can have either at different times.

Perhaps instead of sub-typing based on balanceType perhaps we could look at a model where we sub-type based on the accountCategory /(accountType) something along the lines of the structure below:

            "accounts": [{
                "accountCategory": "...",
                "balance": {
                    "amount": {
                        "currentBalance": {
                            "currency": "..",
                            "amount": "..."
                        },
                        "availableBalance": {
                            "currency": "...",
                            "amount": "..."
                        },
                        "baseCurrencyBalance": {
                            "currency": "...",
                            "amount": "..."
                        }
                    },
                    "purse": {
                        "purse": [{
                            "currency": "...",
                            "currentBalance": "...",
                            "availableBalance": "..."
                        }]
                    }
                }
            }]

We also believe that what’s meant by available funds needs to be clarified. Our assumption is that this would exclude any holds or uncleared funds but would include funds available through utilisation of a creditLimit. Our expectation is that we would present whatever is outlined in our Terms & Conditions for the product.

We agree with previous feedback that facilityLimit could be confusing so support the change of name from facilityLimit to creditLimit. An alternative could be accountLimit.

As stated by others in this thread, inclusion of a mandatory date/timestamp associated with the balance would be a useful addition.

accountCategory

The groupings used in the accountCategory fields may present some mapping challenges. The structure appears to be a mix of product type and product purpose and is not MECE (mutually exclusive & collectively exhaustive) i.e. some products would map to multiple categories which we think is too confusing unless there's an expectation for multi tagging of product types.

Examples of issues:

• A Mortgage could be for a business premises mortgage or a residential mortgage (home loan).
• Business Finance could also cover Line of Credit, Asset Finance, Mortgage
• The requirements for Savings, Transaction & Cash Management are almost identical, and are really different purposes of a generic At Call Deposit

Given the importance of the accountCategory attribute, we propose Data 61 should run short decision paper just on it and its enumerations before finalising Decision Proposal 031 - Detailed Account Payloads.

Closed Accounts We support providing an Open or Closed status, but (as pointed out by others in this thread) Closed Account data is not readily accessible.

[JamesMBligh]

I am leaving this proposal open until COB Monday at the request of a number of stakeholders

-JB-

[MacquarieBank]

Macquarie recommend the following modification to the Basic Account and Balance payloads:

1. In the UK spec, they have a more extensible data model for balances, where a balance is represented by a Type (e.g. Available, Current, etc …), and a credit/debit indicator for each balance. We think this is a more flexible and extensible model (banks could add additional balance types), and will also better handle scenarios where one balance (e.g. current balance) could be positive, and the other balance (e.g. available balance) could be negative (e.g. an overdraft, or a transaction account in negative). We would like Data61 to consider revising balances to more closely align to the UK data model.

2. For accountCategory, we would recommend considering an additional value for OVERDRAFT

[NationalAustraliaBank]

After further consideration and conversations with Data61 NAB would like to share this additional feedback:

• The proposed type names for balance$type may be confusing; as such we would like to propose the following alternatives, as debit and credit may be misleading:

- debit --> deposits
- credit --> lending
- purses --> purses

If balance$type is used as the sub-type field how will the scheme ensure that banks use consistent balance structures for similar product types?

· As requested in the decision proposal, NAB would like to share the following list of potential Account Categories, we also realise that it may be a challenge to expect all banks to map their accounts to these categories as this mapping exercise may be a challenge, as such propose that this mapping be completed on a best efforts or optional basis:

• At Call Deposits (with possible Personal / Business split)
• Term Deposits
• Residential Mortgages (including Residential Line Of Credit)
• Credit & Charge Cards (with possible Personal & Business split)
• Personal Loans
• Leasing (with possible Personal & Business split)
• Trade Finance
• Overdraft (with possible Personal & Business split)
• Business Loans
• Foreign Currency At Call Deposits
• Foreign Currency Term Deposits
• Foreign Currency Loan
• Foreign Currency Overdraft
• Travel Card

[JamesMBligh]

Thanks for the feedback. I am now closing the feedback period pending the formulation of a final recommendation.

-JB-

[JamesMBligh]

Now that the feedback has been fully reviewed here are comments indicating how the final decision will be posed. Note that this decision is for the draft version only. There will be additional time to provide feedback on the whole standard after the draft is released so nothing is set in concrete.

Amortised Limit Ok, this will be added as an additional field

Account ID Permance As per a previous decision proposal record IDs (including the accountId) are designed to be permanent only in the context of a specific authorisation. The intent is to ensure that a new, and potentially sensitive, reusable identifier is not inadvertently created under the CDR regime. As such, there will be no intent to link the accountId to another data delivery mechanism.

Product Data Linkage As previously explained on another decision proposal there is no intention to link an account to a product. This is because there is no guarantee that the product is still offered but also - and more importantly - once the account is created the conditions become more static. The product conditions may change for new accounts that are originated but the existing accounts may or may not be updated to match. This divergence becomes more pronounced over years. To resolve this the same data structures as product (that are relevant) have been included in the account details payload.

Error Codes The 0001 is the code. The rest of the text is explanatory. This would appear to be my poor formatting creating the confusion. I'll try a different approach

accountId Failure Note that this should be an unusual scenario. The usual flow would be to call the accounts end point to get a list of accounts and then refresh the balances later that session after a period of time or at the request of the customer. The recommendation would be for a data consumer to request the list of accounts on a regular basis to ensure access is still available to all accounts. This also has the advantage of picking up newly visible accounts and also changed information on accounts like nickname.

Flexible Balance Type Leaving balance type as open to be specified by data providers creates a potential point of divergence across the providers. This may make it difficult to implement a data consumer across many providers. Preference is for strong typing of balance types. If there is a balance type that is missing let me know in feedback to the draft standard.

Balance Object Will rename to deposits and lending as recommended

Account Category Based on feedback the Account Categories will be renamed as productCategory and set to:

• Personal At Call Deposits
• Business At Call Deposits
• Term Deposits
• Residential Mortgages
• Personal Credit & Charge Cards
• Business Credit & Charge Cards
• Personal Loans
• Personal Leasing
• Business Leasing
• Trade Finance
• Personal Overdraft
• Business Overdraft
• Business Loans
• Foreign Currency At Call Deposits
• Foreign Currency Term Deposits
• Foreign Currency Loan
• Foreign Currency Overdraft
• Travel Card

-JB-

[JamesMBligh]

The finalised decision for this topic has been endorsed. Please refer to the attached document. Decision 027 - Basic Account Payloads.pdf

-JB-