/
Account Access Consents v2.1.0

Account Access Consents v2.1.0

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

2.0.0

Apr 30, 2020

Payments NZ API Working Group

Baseline

2.1-draft1

Jun 15, 2020 

@Gavin Wong (Unlicensed)

Removed:

Errata:

  • Legacy reference to “account request” updated to “account access consent” in Usage Examples

Updated:

  • Usage Example version from v2.0 to v2.1

Definition

The account-access-consents resource represents consents that have been agreed between the Customer and the Third Party for the Third Party to access a Customer's account information with an API Provider.

The Status of an account-access-consent represents the authentication and authorisation stage with the API Provider.

Endpoints

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

account-access-consents

POST /account-access-consents

Mandatory

accounts

Client Credentials

No



NZReadAccessConsent1

NZReadAccessConsentResponse1

account-access-consents

GET /account-access-consents/{ConsentId}

Mandatory

accounts

Client Credentials

No





NZReadAccessConsentResponse1

account-access-consents

DELETE /account-access-consents/{ConsentId}

Mandatory

accounts

Client Credentials

No





 

POST /account-access-consents

The API endpoint allows a Third Party to ask an API Provider to create a new account-access-consent.

  • The Third Party does this with the POST /account-access-consents action.

  • The Third Party must have an access token issued by the API Provider using a client credentials grant.

  • The API endpoint allows the Third Party to send a copy of the consent (between Customer and Third Party) to the API Provider.

  • The API Provider creates the account-access-consent and responds with a unique ConsentId to refer to the consent.

  • At the point the consent is created, the consent has not been authorised.

  • The account-access-consent is only valid for 24 hours if not authorised by the Customer. 

Flow

The Third Party uses the ConsentId to initiate an authorisation flow (as described in the 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 Customer may accept or reject the consent in its entirety (but not selectively).

  • The API Provider presents the Customer a list of accounts that will be linked to the account-access-consent from which the Customer may select one or many.

  • There is no functionality for a Third Party to pre-select a set of accounts that will be linked as part of the consent.

  • The Customer must consent to at least one account or the API Provider rejects the request with a Rejected status.

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

Status

The Status is AwaitingAuthorisation immediately after the account-access-consent has been created.

GET /account-access-consents/{ConsentId}

The API endpoint allows a Third Party to optionally retrieve an account-access-consent that they have created with an API Provider, to check its status. 

  • The Third Party must have an access token issued by the API Provider using a client credentials grant.

Status

The available status codes for the account-access-consent are:

  • AwaitingAuthorisation

  • Rejected

  • Authorised

  • Revoked

DELETE /account-access-consents/{ConsentId}

The API endpoint allows a Third Party to delete the account-access-consent with the API Provider. 

  • This is done by making a call to DELETE the account-access-consents resource.

  • The Third Party must have an access token issued by the API Provider using a client credentials grant.

  • The Third Party must delete the account-access-consent, if the Customer revokes consent to data access with the Third Party.

State Model

The state model for an account-access-consent follows a long-lived consent state model.

  • When the Third Party creates the account-access-consent with the API Provider, the Status of the account-access-consent will be set to AwaitingAuthorisation.

  • When the Customer authorises the account-access-consent with the API Provider, the Status of the account-access-consent will be updated with Authorised.

  • If the Customer rejects the consent or the account-access-consent has failed some other API Provider validation, the Status of the account-access-consent will be set to Rejected.

  • If the Customer revokes the account-access-consent in the Authorised Status with the API Provider, the Status of the account-access-consent will be set to Revoked.

Diagram

This is the state diagram for the status of an account-access-consent.

Definitions

Status

Status Description

Status

Status Description

1

AwaitingAuthorisation

The consent is awaiting Customer authorisation.

  • This is an initial state.

2

Rejected

The consent has been rejected.

  • This is a terminal state.

  • Does not distinguish between failure reasons - e.g. authorisation failed or bank rejected. 

3

Authorised 

The consent has been successfully authorised.

  • This is an intermediate state.

4

Revoked

The consent has been revoked via the API Provider interface.

  • This is a terminal state.

Data Model

Account Access Consent - Request

The NZReadAccessConsent1 object will be used for the call to:

  • POST /account-access-consents

UML Diagram

Notes

  • The fields in the NZReadAccessConsent1 object are also described in the Consent Elements in the Account and Transaction Information page.

Data Dictionary

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

NZReadAccessConsent1



NZReadAccessConsent1



NZReadAccessConsent1



Data

1..1

NZReadAccessConsent1/Data



NZReadDataAccessConsent1



Consent

1..1

NZReadAccessConsent1/Data/Consent

The Consent payload is sent by the Third Party to the API Provider. It is used to request account access for the Customer.

NZAccessConsent1



Permissions

1..n

NZReadAccessConsent1/Data/Consent/Permissions

Specifies the Open Banking account request types. This is a list of the data clusters being consented by the Customer, and requested for authorisation with the API Provider.

OBExternalPermissions2Code

ReadAccountsBasic
ReadAccountsDetail
ReadBalances
ReadBeneficiariesBasic
ReadBeneficiariesDetail
ReadDirectDebits
ReadOffers
ReadParty
ReadPartyAuthUser
ReadScheduledPaymentsBasic
ReadScheduledPaymentsDetail
ReadStandingOrdersBasic
ReadStandingOrdersDetail
ReadStatementsBasic
ReadStatementsDetail
ReadTransactionsBasic
ReadTransactionsCredits
ReadTransactionsDebits
ReadTransactionsDetail

ExpirationDateTime

0..1

NZReadAccessConsent1/Data/Consent/ExpirationDateTime

Specified date and time the permissions will expire.
If this is not populated, the permissions will be open ended.

ISODateTime



TransactionFromDateTime

0..1

NZReadAccessConsent1/Data/Consent/TransactionFromDateTime

Specified start date and time for the transaction query period.
If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction.

ISODateTime



TransactionToDateTime

0..1

NZReadAccessConsent1/Data/Consent/TransactionToDateTime

Specified end date and time for the transaction query period.
If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction.

ISODateTime



Risk

1..1

NZReadAccessConsent1/Risk

The Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.

NZRisk1



Account Access Consent - Response

The NZReadAccessConsentResponse1 object will be used for the call to:

  • GET /account-access-consents/{ConsentId}

and response to:

  • POST /account-access-consents

UML Diagram

Notes

  • The NZReadAccessConsentResponse1 object contains the same information as the NZReadAccessConsent1 - but with additional fields:

    • ConsentId - to uniquely identify the account-access-consent

    • CreationDateTime

    • Status

    • StatusUpdateDateTime

Data Dictionary

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

NZReadAccessConsentResponse1



NZReadAccessConsentResponse1

NZReadAccessConsentResponse1





Data

1..1

NZReadAccessConsentResponse1/Data

NZReadDataAccessConsentResponse1





ConsentId

1..1

NZReadAccessConsentResponse1/Data/ConsentId

Unique identification as assigned to identify the account access consent.

Max128Text



Status

1..1

NZReadAccessConsentResponse1/Data/Status

Specifies the status of the account access consent.

OBExternalConsentStatus1Code

Authorised
AwaitingAuthorisation
Rejected
Revoked

CreationDateTime

1..1

NZReadAccessConsentResponse1/Data/CreationDateTime

Date and time at which the consent was created.

ISODateTime



StatusUpdateDateTime

1..1

NZReadAccessConsentResponse1/Data/StatusUpdateDateTime

Date and time at which the consent status was updated.

ISODateTime



Consent

1..1

NZReadAccessConsentResponse1/Data/Consent

The Consent payload is sent by the Third Party to the API Provider. It is used to request account access for the Customer.

NZAccessConsent1



Permissions

1..n

NZReadAccessConsentResponse1/Data/Consent/Permissions

Specifies the Open Banking account request types. This is a list of the data clusters being consented by the Customer, and requested for authorisation with the API Provider.

OBExternalPermissions2Code

ReadAccountsBasic
ReadAccountsDetail
ReadBalances
ReadBeneficiariesBasic
ReadBeneficiariesDetail
ReadDirectDebits
ReadOffers
ReadParty
ReadPartyAuthUser
ReadScheduledPaymentsBasic
ReadScheduledPaymentsDetail
ReadStandingOrdersBasic
ReadStandingOrdersDetail
ReadStatementsBasic
ReadStatementsDetail
ReadTransactionsBasic
ReadTransactionsCredits
ReadTransactionsDebits
ReadTransactionsDetail

ExpirationDateTime

0..1

NZReadAccessConsentResponse1/Data/Consent/ExpirationDateTime

Specified date and time the permissions will expire.
If this is not populated, the permissions will be open ended.

ISODateTime



TransactionFromDateTime

0..1

NZReadAccessConsentResponse1/Data/Consent/TransactionFromDateTime

Specified start date and time for the transaction query period.
If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction.

ISODateTime



TransactionToDateTime

0..1

NZReadAccessConsentResponse1/Data/Consent/TransactionToDateTime

Specified end date and time for the transaction query period.
If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction.

ISODateTime



Risk

1..1

NZReadAccessConsentResponse1/Risk

The Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.

NZRisk1



Enumerations

This section gives the definitions for enumerations used.

Code Class

Name 

Definition 

Code Class

Name 

Definition 

OBExternalPermissions2Code

ReadAccountsBasic

Permission to read basic account information.

OBExternalPermissions2Code

ReadAccountsDetail

Access to additional elements in the account payload.

OBExternalPermissions2Code