Version Control

Version	Date	Author	Comments
1.0.0	01 March 2019	Payments NZ API Working Group	Baseline specification for Account Requests Resource

Endpoints

	Resource	Endpoint	Mandatory?	Scope	Grant Type	Idempotent	Request Object	Response Object
1	account-requests	POST /account-requests	Mandatory	third_party_client_credential	Client Credentials	No	OBReadRequest1	OBReadResponse1
2	account-requests	GET /account-requests/{AccountRequestId}	Mandatory	third_party_client_credential	Client Credentials			OBReadResponse1
3	account-requests	DELETE /account-requests/{AccountRequestId}	Mandatory	third_party_client_credential	Client Credentials	Yes

Account Request Status

The Customer must authenticate with the API Provider and authorise the account-request for the account-request to be successfully setup.

When the account-request resource is initially created it must have one of the following Status code-list enumerations:

	Status	Status Description
1	Rejected	The account request has been rejected.
2	AwaitingAuthorisation	The account request is awaiting authorisation.

When the Customer has authorised consent the status will be updated to "Authorised".

After authorisation has taken place the account-request resource may have these following status:

	Status	Status Description
3	Authorised	The account request has been successfully authorised.
4	Revoked	The account request has been revoked via the API Provider interface.

This is the state diagram for the status of an account-request

Click here to expand state diagram source...

@startuml

skinparam monochrome true
hide empty description

[*] --> AwaitingAuthorisation
AwaitingAuthorisation -right-> Rejected : [Authorisation has failed, consent authorisation rejected]
AwaitingAuthorisation --> Authorised : [Authorisation is complete]
Authorised->Revoked : [Customer has revoked consent authorisation with API Provider]

@enduml

POST /account-requests

The API allows the Third Party to ask an API Provider to create a new account-request resource.

This API effectively allows the Third Party to send a copy of the consent to the API Provider to authorise access to account information.
There is no functionality for a Third Party to pre-select a set of accounts.
The API Provider creates the account-request resource and responds with a unique AccountRequestId to refer to the resource.
Prior to calling the API, the Third Party must have an access token issued by the API Provider using a client credentials grant.
The Customer must consent to at least one account or the API Provider rejects the request with a rejected status.
Note: the Customer may consent to more than one account in this request.
Note: The account-requests resource may be deleted 24 hours after creation if not authorised by the Customer or, if authorised by the Customer, 24 hours after the specified expiry date.

Available Status

The available Status code-list enumerations for the account-request resource are:

	Status	Status Description
1	Rejected	The account request has been rejected.
2	AwaitingAuthorisation	The account request is awaiting authorisation.

GET /account-requests/{AccountRequestId}

A Third Party can optionally retrieve an account-request resource that they have created to check its status.

Prior to calling the API, the Third Party must have an access token issued by the API Provider using a client credentials grant.

Available Status

The available Status code-list enumerations for the account-request resource are:

	Status	Status Description
1	Rejected	The account request has been rejected.
2	AwaitingAuthorisation	The account request is awaiting authorisation.
3	Authorised	The account request has been successfully authorised.
4	Revoked	The account request has been revoked via the API Provider interface.

DELETE /account-requests/{AccountRequestId}

If the Customer revokes consent to data access with the Third Party - the Third Party must delete the account-request resource.

This is done by making a call to DELETE the account-request resource.
Prior to calling the API, the Third Party must have an access token issued by the API Provider using a client credentials grant.

Data Model

Account Requests - Request

The OBReadRequest1 object will be used for the call to:

POST /account-requests

UML Diagram

Notes

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

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
OBReadRequest1		OBReadRequest1		OBReadRequest1
Data	1..1	OBReadRequest1/Data		OBReadData1
Permissions	1..n	OBReadRequest1/Data/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 ReadProducts ReadScheduledPaymentsBasic ReadScheduledPaymentsDetail ReadStandingOrdersBasic ReadStandingOrdersDetail ReadStatementsBasic ReadStatementsDetail ReadTransactionsBasic ReadTransactionsCredits ReadTransactionsDebits ReadTransactionsDetail
ExpirationDateTime	0..1	OBReadRequest1/Data/ExpirationDateTime	Specified date and time the permissions will expire. If this is not populated, the permissions will be open ended.	ISODateTime
TransactionFromDateTime	0..1	OBReadRequest1/Data/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	OBReadRequest1/Data/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	OBReadRequest1/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 Requests - Response

The OBReadResponse1 object will be used for the call to:

GET /account-requests/{AccountRequestId}

and response to:

POST /account-requests

UML Diagram

Notes

The OBReadResponse1 object contains the same information as the OBReadRequest1 - but with additional fields:
- AccountRequestId - to uniquely identify the account-request resource
- Status
- StatusUpdateDateTime
- CreationDateTime

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
OBReadResponse1		OBReadResponse1		OBReadResponse1
Data	1..1	OBReadResponse1/Data		OBReadDataResponse1
AccountRequestId	1..1	OBReadResponse1/Data/AccountRequestId	Unique identification as assigned to identify the account request resource.	Max128Text
CreationDateTime	1..1	OBReadResponse1/Data/CreationDateTime	Date and time at which the resource was created.	ISODateTime
Status	1..1	OBReadResponse1/Data/Status	Specifies the status of the account request resource.	OBExternalRequestStatus1Code	Authorised AwaitingAuthorisation Rejected Revoked
StatusUpdateDateTime	1..1	OBReadResponse1/Data/StatusUpdateDateTime	Date and time at which the resource status was updated.	ISODateTime
Permissions	1..n	OBReadResponse1/Data/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 ReadPartyPSU ReadProducts ReadScheduledPaymentsBasic ReadScheduledPaymentsDetail ReadStandingOrdersBasic ReadStandingOrdersDetail ReadStatementsBasic ReadStatementsDetail ReadTransactionsBasic ReadTransactionsCredits ReadTransactionsDebits ReadTransactionsDetail
ExpirationDateTime	0..1	OBReadResponse1/Data/ExpirationDateTime	Specified date and time the permissions will expire. If this is not populated, the permissions will be open ended.	ISODateTime
TransactionFromDateTime	0..1	OBReadResponse1/Data/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	OBReadResponse1/Data/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	OBReadResponse1/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	ReadAccountsBasic	Ability to read basic account information
OBExternalPermissions1Code	ReadAccountsDetail	Ability to read account identification details
OBExternalPermissions1Code	ReadBalances	Ability 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 request has been successfully authorised.
OBExternalRequestStatus1Code	AwaitingAuthorisation	The account request is awaiting further authorisation.
OBExternalRequestStatus1Code	Rejected	The account request has been rejected.
OBExternalRequestStatus1Code	Revoked	The account request has been revoked via the API Provider interface.

Usage Examples

Setup Account Request

Request

POST Account Requests Request

POST /account-requests HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-customer-last-logged-time: 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": {
    "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": {
    "AccountRequestId": "88379",
    "Status": "AwaitingAuthorisation",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "StatusUpdateDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances"
    ],
    "ExpirationDateTime": "2017-08-02T00:00:00+00:00"
  },
  "Risk": {},
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/account-requests/88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Status - AwaitingAuthorisation

This is an example of a GET request which is made before the account request resource is authorised.

Request

GET Account Requests Request

GET /account-requests/88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-customer-last-logged-time: 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": {
    "AccountRequestId": "88379",
    "Status": "AwaitingAuthorisation",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "StatusUpdateDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances"
    ],
    "ExpirationDateTime": "2017-08-02T00:00:00+00:00"
  },
  "Risk": {},
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/account-requests/88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Status - Authorised

This is an example of a GET request which is made after the account request resource is authorised.

Request

GET Account Requests Request

GET /account-requests/88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-customer-last-logged-time: 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": {
    "AccountRequestId": "88379",
    "Status": "Authorised",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "StatusUpdateDateTime": "2017-05-02T00:05:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances"
    ],
    "ExpirationDateTime": "2017-08-02T00:00:00+00:00"
  },
  "Risk": {},
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/account-requests/88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Delete Account Request

The DELETE /account-requests call allows a Third Party to delete a previously created account-request (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-request which is deleted.

Request

DELETE Account Requests Request

DELETE /account-requests/88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-customer-last-logged-time: 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

Setup Account Request with All Permissions

Request

POST Account Requests Request

POST /account-requests HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-customer-last-logged-time: 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": {
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesDetail",
      "ReadDirectDebits",
      "ReadProducts",
      "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": {
    "AccountRequestId": "88379",
    "Status": "AwaitingAuthorisation",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesDetail",
      "ReadDirectDebits",
      "ReadProducts",
      "ReadStandingOrdersDetail",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail",
      "ReadOffers",
      "ReadPAN",
      "ReadParty",
      "ReadPartyA",
      "ReadScheduledPaymentsDetail",
      "ReadStatementsDetail"
    ],
    "ExpirationDateTime": "2017-08-02T00:00:00+00:00"
  },
  "Risk": {},
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/account-requests/88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Payments NZ API standards

Account Requests v1.0.0

Contents

Version Control

Endpoints

Account Request Status

POST /account-requests

Available Status

GET /account-requests/{AccountRequestId}

Available Status

DELETE /account-requests/{AccountRequestId}

Data Model

Account Requests - Request

UML Diagram

Notes

Data Dictionary

Account Requests - Response

UML Diagram

Notes

Data Dictionary

Enumerations

Usage Examples

Setup Account Request

Status - AwaitingAuthorisation

Status - Authorised

Delete Account Request

Setup Account Request with All Permissions