Version Control
| Version | Date | Author | Comments |
|---|---|---|---|
| 1.0.0 | 01 March 2019 | Payments NZ API Working Group | Baseline specification for Account Requests Resource |
| v2.0-draft1 | Updates:
Added: Errata:
| ||
| v2.0-draft2 | Gavin Wong (Unlicensed) | Updates:
Errata:
| |
| v2.0-draft3 | Gavin Wong (Unlicensed) | Updates:
Errata:
|
Definition
The account-access-consent resource represents a consent that has 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 the 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 |
|---|---|---|---|---|---|---|---|---|
| account-access-consents | POST /account-access-consents | Mandatory | third_party_client_credential | Client Credentials | No | NZReadAccessConsent1 | NZReadAccessConsentResponse1 | |
| account-access-consents | GET /account-access-consents/{ConsentId} | Mandatory | third_party_client_credential | Client Credentials | No | NZReadAccessConsentResponse1 | ||
| account-access-consents | DELETE /account-access-consents/{ConsentId} | Mandatory | third_party_client_credential | 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 resource.
- 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 resource and responds with a unique ConsentId to refer to the resource.
- At the point the consent resource is created, the consent has not been authorised.
- The account-access-consent resource is only valid for 24 hours if not authorised by the Customer.
- An API Provider may delete the account-access-consent resource 24 hours after creation if not authorised by the Customer or, if authorised by the Customer, 24 hours after the specified expiry date.
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 resource 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 resource 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-consent 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 resource, if the Customer revokes consent to data access with the Third Party.
State Model
The state model for the account-access-consent resource follows a long lived consent state model.
- When the Third Party creates the account-access-consent resource with the API Provider, the Status of the account-access-consent resource will be set to "AwaitingAuthorisation".
- When the Customer authorises the account-access-consent resource with the API Provider, the Status of the account-access-consent resource 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 resource 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 resource will be set to "Revoked".
Diagram
This is the state diagram for the status of the account-access-consent resource.
Definitions
| Status | Status Description | |
|---|---|---|
| 1 | AwaitingAuthorisation | The consent resource is awaiting Customer authorisation.
|
| 2 | Rejected | The consent resource has been rejected.
|
| 3 | Authorised | The consent resource has been successfully authorised.
|
| 4 | Revoked | The consent resource has been revoked via the API Provider interface.
|
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. | OBExternalPermissions1Code | ReadAccountsBasic ReadAccountsDetail ReadBalances ReadBeneficiariesBasic ReadBeneficiariesDetail ReadDirectDebits ReadOffers ReadPAN 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 resource
- 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 request resource. | Max128Text | |
| Status | 1..1 | NZReadAccessConsentResponse1/Data/Status | Specifies the status of the account request resource. | OBExternalConsentStatus1Code | Authorised AwaitingAuthorisation Rejected Revoked |
| CreationDateTime | 1..1 | NZReadAccessConsentResponse1/Data/CreationDateTime | Date and time at which the resource was created. | ISODateTime | |
| StatusUpdateDateTime | 1..1 | NZReadAccessConsentResponse1/Data/StatusUpdateDateTime | Date and time at which the resource 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. | OBExternalPermissions1Code | ReadAccountsBasic ReadAccountsDetail ReadBalances ReadBeneficiariesBasic ReadBeneficiariesDetail ReadDirectDebits ReadOffers ReadPAN 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 |
|---|---|---|
| OBExternalPermissions1Code | ReadAccountsBasic | Permission to read basic account information. |
| OBExternalPermissions1Code | ReadAccountsDetail | Access to additional elements in the account payload. |
| OBExternalPermissions1Code | ReadBalances | Permission to read all balance information. |
| OBExternalPermissions1Code | ReadBeneficiariesBasic | Ability to read basic beneficiary details |
| OBExternalPermissions1Code | ReadBeneficiariesDetail | Ability to read account identification details for the beneficiary |
| OBExternalPermissions1Code | ReadDirectDebits | Ability to read all direct debit information |
| OBExternalPermissions1Code | ReadOffers | Ability to read all offer information |
| OBExternalPermissions1Code | ReadPAN | Request to access PAN in the clear across the available endpoints. If this permission code is not in the account-request, the Third Party will receive a masked PAN.While a Third Party may request to access PAN in the clear, an API Provider may still respond with a masked PAN if the API Provider takes a legal view to respond with only the masked PAN. |
| OBExternalPermissions1Code | ReadParty | Ability to read party information on the account owner. |
| OBExternalPermissions1Code | ReadPartyAuthUser | Ability to read party information on the user logged in. |
| OBExternalPermissions1Code | ReadScheduledPaymentsBasic | Ability to read basic statement details |
| OBExternalPermissions1Code | ReadScheduledPaymentsDetail | Ability to read account identification details for beneficiary of the scheduled payment |
| OBExternalPermissions1Code | ReadStandingOrdersBasic | Ability to read basic standing order information |
| OBExternalPermissions1Code | ReadStandingOrdersDetail | Ability to read account identification details for beneficiary of the standing order |
| OBExternalPermissions1Code | ReadStatementsBasic | Ability to read basic statement details |
| OBExternalPermissions1Code | ReadStatementsDetail | Ability to read statement data elements which may leak other information about the account |
| OBExternalPermissions1Code | ReadTransactionsBasic | Ability to read basic transaction information |
| OBExternalPermissions1Code | ReadTransactionsCredits | Ability to read only credit transactions |
| OBExternalPermissions1Code | ReadTransactionsDebits | Ability to read only debit transactions |
| OBExternalPermissions1Code | 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 Requests Request
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 Requests Response
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.0/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 resource is authorised.
Request
GET Account Requests Request
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 Requests Response
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.0/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 resource is authorised.
Request
GET Account Requests Request
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 Requests Response
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.0/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 Requests Request
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 Accounts Response
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 Requests Request
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",
"ReadPAN",
"ReadParty",
"ReadPartyAuthUser",
"ReadScheduledPaymentsDetail",
"ReadStatementsDetail"
],
"ExpirationDateTime":"2017-05-02T00:00:00+00:00"
}
},
"Risk":{}
}
Response
POST Account Requests Response
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",
"ReadPAN",
"ReadParty",
"ReadPartyAuthUser",
"ReadScheduledPaymentsDetail",
"ReadStatementsDetail"
],
"ExpirationDateTime":"2017-08-02T00:00:00+00:00"
}
},
"Risk":{},
"Links":{
"Self":"https://examplebank.api.co.nz/open-banking-nz/v2.0/account-access-consents/88379"
},
"Meta":{
"TotalPages":1
}
}
0 Comments