Version | Date | Author | Comments |
---|---|---|---|
1.0.0 | 01 March 2019 | Payments NZ API Working Group | Baseline specification for Account Requests Resource |
Resource | Endpoint | Mandatory? | Scope | Grant Type | Idempotent | Parameters | 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 |
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
@startuml skinparam monochrome true
|
The API allows the Third Party to ask an API Provider to create a new account-request resource.
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. |
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.
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. |
If the Customer revokes consent to data access with the Third Party - the Third Party must delete the account-request resource.
The OBReadRequest1 object will be used for the call to:
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 |
The OBReadResponse1 object will be used for the call to:
and response to:
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 |
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. |
Request
|
Response
|
This is an example of a GET request which is made before the account request resource is authorised.
Request
|
Response
|
This is an example of a GET request which is made after the account request resource is authorised.
Request
|
Response
|
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
|
Response
|
Request
|
Response
|