• An API Provider must allow a token that is bound to a Consent in a lower version, to be used to access account information endpoints in a higher version.
  • E.g., a token issued from an authorization code grant using an account-access-consent ConsentId from v2 must be allowed to be used to access GET /accounts in v3.

• An API Provider must not allow an account-access-consent created on a higher version, to be used to access account information resources in a lower version.

  • E.g., a ConsentId created in v2, must not be used to access v1 account information endpoints

GET

• An API Provider must allow an account-access-consent created on a lower version, to be accessed via a higher version. In the case where the account-access-consent is the same, but the structure has changed in a higher version, sensible defaults must be used, with the API Provider's developer portal clearly specifying the behaviour.
  
  • E.g., a ConsentId created in v2 must be allowed be accessed via v3, as this is a long lived consent.
• An API Provider must not allow an account-access-consent created on a higher version, to be accessed via a lower version.
  • E.g., a ConsentId created in v3 must not be accessed via v2.
• An API Provider must ensure the Consent object (including the Permissions) in an account-access-consent is unchanged when accessed in a different version.
  • E.g., an account-access-consent created in v2 will have the same Consent object when accessed via v2 and v3.
• An API Provider may allow an expired account-access-consent created on a lower version, to be accessed via a higher version.
  • E.g., an expired ConsentId created in v2 may be accessed via v3.

DELETE

• An API Provider must not allow an account-access-consent created in a higher version, to be deleted in a lower version.
  • E.g., a ConsentId created in v3 must not allowed to be deleted via v2.
• An API Provider must allow an account-access-consent created in a lower version, to be deleted in a higher version.
  • E.g., a ConsentId created in v1 must be allowed to be deleted via v2.

Account Information Resources

GET

• An API Provider must allow a token that is bound to a Consent in a lower version, to access account information endpoints of a higher version. 
  • E.g., a token issued from an authorization code grant using an AccountRequestId from v1 must be allowed to be used to access GET /accounts in v2.
• An API Provider must allow an account-access-consent created in a lower version, to access account information endpoints of a higher version.
  • E.g., an AccountRequestId from v1 must be allowed to be used as the ConsentId in v2 to access GET /accounts.
• An API Provider must not allow an account-access-consent created in a higher version, to access account information endpoints of a lower version.
  • E.g., ConsentId for an account-access-consent created in v3, must not be used to access v2 Account Information endpoints.
• An API Provider must not allow an account-access-consent created in a lower version, to access a resource introduced in a higher version (as the Consent object will not have Permissions required to access the new resource).
  • E.g., 
• An API Provider may choose to populate new fields introduced in a higher version with sensible defaults (if mandatory) or not populate at all.

Endpoints

This section looks at the list of available API endpoints to access Account Information and optionality.

• The API Provider must implement the API endpoints in the table below that are marked as Mandatory.
• The API Provider may optionally implement the API endpoints that are marked as Optional.
• If an API Provider has not implemented an API endpoint marked as Optional, the API Provider must respond with a 501 (Not Implemented) for requests to that API endpoint.

Endpoint design considerations:

• Having resources that are finer grained (e.g., beneficiaries, direct-debits, standing-orders) means that we can, in the future, manage these resources (with unique identifiers)
• While balances is not a typical resource - we believe having an /accounts/{AccountId}/balances endpoint is simpler to understand than a URI to expand the /accounts resource 

Account Information Resources

Each of the high level resources are documented in sub-pages of the Account Information API specification with these sections:

• Definition
• Endpoints
• Data Model
  • UML Diagram
  • Notes
  • Filtering
  • Permission Codes - as they relate to accessing the resource
  • Data Dictionary - which defines fields, re-usable classes
  • Enumerations
• Usage Examples

Security & Access Control

Scopes

The access tokens required for accessing the Account Information APIs must have one of the following scopes:

third_party_client_credential
accounts

Grants Types

Third Parties must use a client credentials grant to obtain a token with the scope third_party_client_credential to make:

• POST requests to the account-access-consents resource.
• GET requests to the account-access-consents resource.
• DELETE requests to the account-access-consents resource.

Third Parties must use an authorisation flow using a redirect or decoupled flow to obtain a token with the scope accounts to make:

• GET requests to access all other account information resources (i.e., all resources other than account-access-consents).

Consent Authorisation

The Third Party must create an account-access-consent resource through a POST operation. This resource indicates the consent that the Third Party claims it has been given by the Customer to retrieve account and transaction information. At this stage, the consent is not yet authorised as the API Provider has not yet verified this claim with the Customer.

The API Provider responds with a ConsentId. This is the ConsentId that is used when initiating an authorisation flow (as described in the NZ Banking Data Security Profile).

As part of the authorisation flow:

• The API Provider authenticates the Customer.
• The API Provider plays back the consent (registered by the Third Party) back to the Customer - to get consent authorisation.
• The API Provider presents the Customer a list of accounts from which the Customer must select the account or accounts that apply to the consent.
• The Customer may accept or reject the consent in its entirety (but not selectively).

Once these steps are complete, the consent is considered to have been authorised by the Customer.

Consent Elements

The account-access-consent resource consists of the following fields, that together form the elements of the consent provided by the Customer to the Third Party:

• Permissions: The set of data clusters that the Customer has consented to allow the Third Party to access
• ExpirationDateTime: The date-time up to which the consent is valid.
• TransactionFromDateTime: The earliest point of the transaction / statement historical period that the Customer has consented to provide access to the Third Party.
• TransactionToDateTime: The last point of the transaction / statement historical period that the Customer has consented to provide access to the Third Party.

Permissions

Permissions codes will be used to limit the data that is returned in response to a resource request. 

• When permission is granted for a "Detail" permission code (e.g., ReadAccountsDetail), it implies that access is also granted to the corresponding "Basic" permission code (e.g., ReadAccountsBasic)
• While it is duplication for a Third Party to request a "Basic" permission code and the corresponding "Detail" permission code, it is not a malformed request, and the API Provider must not reject the request solely on the basis of duplication

The API Provider must reject account-access-consents with a 400 response code when:

• The Permissions array does not contain either ReadAccountsBasic or ReadAccountsDetail
• The Permissions array is empty
• The Permissions array includes a Permission code that is not supported by the API Provider (API Providers are expected to publish which API endpoints are supported)
• The Permissions array contains ReadTransactionsBasic but does not contain at least one of ReadTransactionsCredits and ReadTransactionsDebits
• The Permissions array contains ReadTransactionsDetail but does not contain at least one of ReadTransactionsCredits and ReadTransactionsDebits
• The Permissions array contains ReadTransactionsCredits but does not contain at least one of ReadTransactionsBasic and ReadTransactionsDetail
• The Permissions array contains ReadTransactionsDebits but does not contain at least one of ReadTransactionsBasic and ReadTransactionsDetail

All other fields (other than these fields listed) are available with the "Basic" Permission access. 

Example behaviour of the Permissions for the ReadAccountsBasic and ReadAccountDetail codes is as follows:

Expiration Date Time

The ExpirationDateTime is an optional field which specifies the expiration for Third Party access to the Customer's data.

The ExpirationDateTime is optional - as the consent for Third Party access to a Customer's data can be indefinite.

If no ExpirationDateTime is provided, the API Provider will determine the validity period of the accounts request.

The ExpirationDateTime will also apply to the refresh token, if issued.

The ExpirationDateTime applies to all Permissions (data clusters) being consented.

The API Provider must reject account-access-consents with a 400 response code when:

• The ExpirationDateTime value is in the past

Transaction To/From Date Time

The TransactionToDateTime and the TransactionFromDateTime specify the period for consented transaction and/or statement history. 

Both the TransactionToDateTime and the TransactionFromDateTime are optional and one may be specified without the other.

The API Provider must restrict access to transactions between the TransactionToDateTime and TransactionFromDateTime when a Third Party accesses the transactions resource.

The API Provider must restrict access to statements which are completely within this period when a Third Party accesses the statements resource.

The API Provider must reject account-access-consents with a 400 response code when:

• The TransactionToDateTime value is in the past
• The TransactionToDateTime not greater than the TransactionFromDateTime

Consent Re-authorisation

An API Provider may allow a Customer to re-authorise an account access consent (as it is a long-lived consent) if:

• The account-access-consent has a status of Authorised; and 
• The ExpirationDateTime of the account-access-consent has not elapsed.

An API Provider may allow the Customer to update the linked accounts during consent re-authorisation.

Consent Revocation

A Customer may revoke consent for accessing account information at any point in time.

The Customer may revoke authorisation directly with the API Provider. The mechanisms for this are in the competitive space and are up to each API Provider to implement in the API Provider's banking interface. If the Customer revokes authorisation with the API Provider, the Status of the account-request resource must be set to Revoked.

The Customer may request the Third Party to revoke consent that it has authorised. If consent is revoked with the Third Party:

• The Third Party must cease to access the APIs at that point.
• The Third Party must call the DELETE operation on the account-request resource (before confirming consent revocation with the Customer) to indicate to the API Provider that the Customer has revoked consent.

Consent Updates

An API Provider must not allow a Customer to update the parameters of an account-access-consent.

Selected Accounts

The Customer must select the accounts to which the consent is linked at the point of consent authorisation.

Subsequent changes to the set of accounts to which the consent authorisation applies may be carried out directly with the API Provider. The method for doing this lies in the competitive space and is not part of this specification.

Additionally, the set of selected accounts may also change due to external factors. This includes (but is not limited to):

• The account being closed.
• The Customer's mandate to operate the account is revoked.
• The account is barred or frozen.
• The Customer changes the selected accounts during consent re-authorisation.

In such a situation, only the affected account is removed from the list of selected accounts. The API Provider must not revoke authorisation to other accounts.

  "Meta": {
    "TotalPages": 1,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }

The Swagger Specification for the Account Information APIs can be downloaded from https://github.com/PaymentsDirection/API-Account-Information