Table of Contents

outline	true

Version Control

Include Page

	PaymentsNZAPIStandardsPaymentsDirectionAPIStandardsDevelopment:Version Control - Account Information v3.0.1PaymentsNZAPIStandards
	PaymentsDirectionAPIStandardsDevelopment:Version Control - Account Information v3.0.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	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
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
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
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
OBExternalPermissions2Code	ReadAccountsBasic	Permission to read basic account information.
OBExternalPermissions2Code	ReadAccountsDetail	Access to additional elements in the account payload.
OBExternalPermissions2Code	ReadBalances	Permission to read all balance information.
OBExternalPermissions2Code	ReadBeneficiariesBasic	Ability to read basic beneficiary details
OBExternalPermissions2Code	ReadBeneficiariesDetail	Ability to read account identification details for the beneficiary
OBExternalPermissions2Code	ReadDirectDebits	Ability to read all direct debit information
OBExternalPermissions2Code	ReadOffers	Ability to read all offer information
OBExternalPermissions2Code	ReadParty	Ability to read party information on the account owner.
OBExternalPermissions2Code	ReadPartyAuthUser	Ability to read party information on the user logged in.
OBExternalPermissions2Code	ReadScheduledPaymentsBasic	Ability to read basic statement details
OBExternalPermissions2Code	ReadScheduledPaymentsDetail	Ability to read account identification details for beneficiary of the scheduled payment
OBExternalPermissions2Code	ReadStandingOrdersBasic	Ability to read basic standing order information
OBExternalPermissions2Code	ReadStandingOrdersDetail	Ability to read account identification details for beneficiary of the standing order
OBExternalPermissions2Code	ReadStatementsBasic	Ability to read basic statement details
OBExternalPermissions2Code	ReadStatementsDetail	Ability to read statement data elements which may leak other information about the account
OBExternalPermissions2Code	ReadTransactionsBasic	Ability to read basic transaction information
OBExternalPermissions2Code	ReadTransactionsCredits	Ability to read only credit transactions
OBExternalPermissions2Code	ReadTransactionsDebits	Ability to read only debit transactions
OBExternalPermissions2Code	ReadTransactionsDetail	Ability to read transaction data elements which may hold silent party details
OBExternalRequestStatus1Code	Authorised	The account access consent has been successfully authorised.
OBExternalRequestStatus1Code	AwaitingAuthorisation	The account access consent is awaiting further authorisation.
OBExternalRequestStatus1Code	Rejected	The account access consent has been rejected.
OBExternalRequestStatus1Code	Revoked	The account access consent has been revoked via the API Provider interface.

Usage Examples

Create Account Access Consent

This is an example of an account-access-consent with limited permissions - viewing account details and querying the balance.

Request

POST Account Access Consent Request

Code Block

POST /account-access-consents HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
 
{  
    "Data":{  
        "Consent":{  
            "Permissions":[  
                "ReadAccountsDetail",
                "ReadBalances"
            ],
            "ExpirationDateTime":"2017-05-02T00:00:00+00:00"
        }
    },
    "Risk":{}
}

Response

POST Account Access Consent Response

Code Block

HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{  
    "Data":{  
        "ConsentId":"88379",
        "Status":"AwaitingAuthorisation",
        "CreationDateTime":"2017-05-02T00:00:00+00:00",
        "StatusUpdateDateTime":"2017-05-02T00:00:00+00:00",
        "Consent":{  
            "Permissions":[  
                "ReadAccountsDetail",
                "ReadBalances"
            ],
            "ExpirationDateTime":"2017-08-02T00:00:00+00:00"
        }
    },
    "Risk":{},
    "Links":{  
        "Self":"https://examplebank.api.co.nz/open-banking-nz/v2.1/account-access-consents/88379"
    },
    "Meta":{  
        "TotalPages":1
    }
}

Status - AwaitingAuthorisation

This is an example of a GET request which is made before the account-access-consent is authorised.

Request

GET Account Access Consent Request

Code Block

GET /account-access-consents/88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Response

GET Account Access Consent Response

Code Block

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json 

{  
    "Data":{  
        "ConsentId":"88379",
        "CreationDateTime":"2017-05-02T00:00:00+00:00",
        "Status":"AwaitingAuthorisation",
        "CreationDateTime":"2017-05-02T00:00:00+00:00",
        "StatusUpdateDateTime":"2017-05-02T00:00:00+00:00",
        "Consent":{  
            "Permissions":[  
                "ReadAccountsDetail",
                "ReadBalances"
            ],
            "ExpirationDateTime":"2017-08-02T00:00:00+00:00"
        }
    },
    "Risk":{},
    "Links":{  
        "Self":"https://examplebank.api.co.nz/open-banking-nz/v2.1/account-access-consents/88379"
    },
    "Meta":{  
        "TotalPages":1
    }
}

Status - Authorised

This is an example of a GET request which is made after the account-access-consent is authorised.

Request

GET Account Access Consent Request

Code Block

GET /account-access-consents/88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Response

GET Account Access Consent Response

Code Block

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json 

{  
    "Data":{  
        "ConsentId":"88379",
        "CreationDateTime":"2017-05-02T00:00:00+00:00",
        "Status":"Authorised",
        "StatusUpdateDateTime":"2017-05-02T00:05:00+00:00",
        "Consent":{  
            "Permissions":[  
                "ReadAccountsDetail",
                "ReadBalances"
            ],
            "ExpirationDateTime":"2017-08-02T00:00:00+00:00"
        }
    },
    "Risk":{},
    "Links":{
        "Self":"https://examplebank.api.co.nz/open-banking-nz/v2.1/account-access-consents/88379"
    },
    "Meta":{  
        "TotalPages":1
    }
}

Delete Account Access Consent

The DELETE /account-access-consents call allows a Third Party to delete a previously created account-access-consent (whether it is currently authorised or not). The Customer may want to remove their consent via the Third Party instead of revoking authorisation with the API Provider.

This API call allows the Customer to revoke consent with the Third Party - and for that consent to be reflected in authorisation with the API Provider. The API Provider will remove the consent related to the account-access-consent which is deleted.

Request

DELETE Account Access Consent Request

Code Block

DELETE /account-access-consents/88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Response

DELETE Account Access Consent Response

Code Block
HTTP/1.1 204 No Content x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d

Create Account Access Consent with All Permissions

This is an example of an account-access-consent with all available permissions.

Request

POST Account Access Consent Request

Code Block

POST /account-access-consents HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
 
{  
    "Data":{  
        "Consent":{  
            "Permissions":[  
                "ReadAccountsDetail",
                "ReadBalances",
                "ReadBeneficiariesDetail",
                "ReadDirectDebits",
                "ReadStandingOrdersDetail",
                "ReadTransactionsCredits",
                "ReadTransactionsDebits",
                "ReadTransactionsDetail",
                "ReadOffers",
                "ReadParty",
                "ReadPartyAuthUser",
                "ReadScheduledPaymentsDetail",
                "ReadStatementsDetail"
            ],
            "ExpirationDateTime":"2017-05-02T00:00:00+00:00"
        }
    },
    "Risk":{}
}

Response

POST Account Access Consent Response

Code Block

HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{  
    "Data":{  
        "ConsentId":"88379",
        "CreationDateTime":"2017-05-02T00:00:00+00:00",
        "Status":"AwaitingAuthorisation",
        "StatusUpdateDateTime":"2017-05-02T00:00:00+00:00",
        "Consent":{  
            "Permissions":[  
                "ReadAccountsDetail",
                "ReadBalances",
                "ReadBeneficiariesDetail",
                "ReadDirectDebits",
                "ReadStandingOrdersDetail",
                "ReadTransactionsCredits",
                "ReadTransactionsDebits",
                "ReadTransactionsDetail",
                "ReadOffers",
                "ReadParty",
                "ReadPartyAuthUser",
                "ReadScheduledPaymentsDetail",
                "ReadStatementsDetail"
            ],
            "ExpirationDateTime":"2017-08-02T00:00:00+00:00"
        }
    },
    "Risk":{},
    "Links":{  
        "Self":"https://examplebank.api.co.nz/open-banking-nz/v2.1/account-access-consents/88379"
    },
    "Meta":{  
        "TotalPages":1
    }
}

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Version Control

Definition

Endpoints

POST /account-access-consents

Flow

Status

GET /account-access-consents/{ConsentId}

Status

DELETE /account-access-consents/{ConsentId}

State Model

Diagram

Definitions

Data Model

Account Access Consent - Request

UML Diagram

Notes

Data Dictionary

Account Access Consent - Response

UML Diagram

Notes

Data Dictionary

Enumerations

Usage Examples

Create Account Access Consent

Request

POST Account Access Consent Request

Response

POST Account Access Consent Response

Status - AwaitingAuthorisation

Request

GET Account Access Consent Request

Response

GET Account Access Consent Response

Status - Authorised

Request

GET Account Access Consent Request

Response

GET Account Access Consent Response

Delete Account Access Consent

Request

DELETE Account Access Consent Request

Response

DELETE Account Access Consent Response

Create Account Access Consent with All Permissions

Request

POST Account Access Consent Request

Response

POST Account Access Consent Response