Versions Compared

Old Version 1

changes.mady.by.user Gavin Wong

Saved on

compared with

New Version Current

changes.mady.by.user Gavin Wong

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Contents

Table of Contents
outlinetrue

Version Control


Version
Date
Author
Comments
1.0.001 March 2019Payments NZ API Working GroupBaseline specification for Account Requests Resource


Endpoints



ResourceEndpointMandatory?ScopeGrant TypeIdempotentParametersRequest ObjectResponse Object
1account-requestsPOST /account-requestsMandatorythird_party_client_credentialClient CredentialsNo
OBReadRequest1OBReadResponse1
2account-requestsGET /account-requests/{AccountRequestId}Mandatorythird_party_client_credentialClient Credentials


OBReadResponse1
3account-requestsDELETE /account-requests/{AccountRequestId}Mandatorythird_party_client_credentialClient CredentialsYes



...



StatusStatus Description
1RejectedThe account request has been rejected.
2AwaitingAuthorisationThe account request is awaiting authorisation.
3AuthorisedThe account request has been successfully authorised.
4RevokedThe 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


NameOccurrenceXPathEnhancedDefinitionClassCodes
OBReadRequest1
OBReadRequest1
OBReadRequest1
Data1..1OBReadRequest1/Data
OBReadData1
Permissions1..nOBReadRequest1/Data/PermissionsSpecifies 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.OBExternalPermissions1CodeReadAccountsBasic
ReadAccountsDetail
ReadBalances
ReadBeneficiariesBasic
ReadBeneficiariesDetail
ReadDirectDebits
ReadOffers
ReadPAN
ReadParty
ReadPartyAuthUser
ReadProducts
ReadScheduledPaymentsBasic
ReadScheduledPaymentsDetail
ReadStandingOrdersBasic
ReadStandingOrdersDetail
ReadStatementsBasic
ReadStatementsDetail
ReadTransactionsBasic
ReadTransactionsCredits
ReadTransactionsDebits
ReadTransactionsDetail
ExpirationDateTime0..1OBReadRequest1/Data/ExpirationDateTimeSpecified date and time the permissions will expire.
If this is not populated, the permissions will be open ended.		ISODateTime
TransactionFromDateTime0..1OBReadRequest1/Data/TransactionFromDateTimeSpecified 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
TransactionToDateTime0..1OBReadRequest1/Data/TransactionToDateTimeSpecified 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
Risk1..1OBReadRequest1/RiskThe 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


NameOccurrenceXPathEnhancedDefinitionClassCodes
OBReadResponse1
OBReadResponse1
OBReadResponse1
Data1..1OBReadResponse1/Data
OBReadDataResponse1
AccountRequestId1..1OBReadResponse1/Data/AccountRequestIdUnique identification as assigned to identify the account request resource.Max128Text
CreationDateTime1..1OBReadResponse1/Data/CreationDateTimeDate and time at which the resource was created.ISODateTime
Status1..1OBReadResponse1/Data/StatusSpecifies the status of the account request resource.OBExternalRequestStatus1CodeAuthorised
AwaitingAuthorisation
Rejected
Revoked
StatusUpdateDateTime1..1OBReadResponse1/Data/StatusUpdateDateTimeDate and time at which the resource status was updated.ISODateTime
Permissions1..nOBReadResponse1/Data/PermissionsSpecifies 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.OBExternalPermissions1CodeReadAccountsBasic
ReadAccountsDetail
ReadBalances
ReadBeneficiariesBasic
ReadBeneficiariesDetail
ReadDirectDebits
ReadOffers
ReadPAN
ReadParty
ReadPartyPSU
ReadProducts
ReadScheduledPaymentsBasic
ReadScheduledPaymentsDetail
ReadStandingOrdersBasic
ReadStandingOrdersDetail
ReadStatementsBasic
ReadStatementsDetail
ReadTransactionsBasic
ReadTransactionsCredits
ReadTransactionsDebits
ReadTransactionsDetail
ExpirationDateTime0..1OBReadResponse1/Data/ExpirationDateTimeSpecified date and time the permissions will expire.
If this is not populated, the permissions will be open ended.		ISODateTime
TransactionFromDateTime0..1OBReadResponse1/Data/TransactionFromDateTimeSpecified 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
TransactionToDateTime0..1OBReadResponse1/Data/TransactionToDateTimeSpecified 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
Risk1..1OBReadResponse1/RiskThe 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 ClassName Definition 
OBExternalPermissions1CodeReadAccountsBasicPermission to read basic account information.
OBExternalPermissions1CodeReadAccountsDetailAccess to additional elements in the account payload.
OBExternalPermissions1CodeReadBalancesPermission to read all balance information.
OBExternalPermissions1CodeReadAccountsBasicAbility to read basic account information
OBExternalPermissions1CodeReadAccountsDetailAbility to read account identification details
OBExternalPermissions1CodeReadBalancesAbility to read all balance information
OBExternalPermissions1CodeReadBeneficiariesBasicAbility to read basic beneficiary details
OBExternalPermissions1CodeReadBeneficiariesDetailAbility to read account identification details for the beneficiary
OBExternalPermissions1CodeReadDirectDebitsAbility to read all direct debit information
OBExternalPermissions1CodeReadOffersAbility to read all offer information
OBExternalPermissions1CodeReadPAN

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.

OBExternalPermissions1CodeReadPartyAbility to read party information on the account owner.
OBExternalPermissions1CodeReadPartyAuthUserAbility to read party information on the user logged in.
OBExternalPermissions1CodeReadScheduledPaymentsBasicAbility to read basic statement details
OBExternalPermissions1CodeReadScheduledPaymentsDetailAbility to read account identification details for beneficiary of the scheduled payment
OBExternalPermissions1CodeReadStandingOrdersBasicAbility to read basic standing order information
OBExternalPermissions1CodeReadStandingOrdersDetailAbility to read account identification details for beneficiary of the standing order
OBExternalPermissions1CodeReadStatementsBasicAbility to read basic statement details
OBExternalPermissions1CodeReadStatementsDetailAbility to read statement data elements which may leak other information about the account
OBExternalPermissions1CodeReadTransactionsBasicAbility to read basic transaction information
OBExternalPermissions1CodeReadTransactionsCreditsAbility to read only credit transactions
OBExternalPermissions1CodeReadTransactionsDebitsAbility to read only debit transactions
OBExternalPermissions1CodeReadTransactionsDetailAbility to read transaction data elements which may hold silent party details
OBExternalRequestStatus1CodeAuthorisedThe account request has been successfully authorised.
OBExternalRequestStatus1CodeAwaitingAuthorisationThe account request is awaiting further authorisation.
OBExternalRequestStatus1CodeRejectedThe account request has been rejected.
OBExternalRequestStatus1CodeRevokedThe account request has been revoked via the API Provider interface.



Usage Examples

Setup Account Request


Column
width50%

Request

Code Block
languagejs
themeMidnight
firstline1
titlePOST Account Requests Request
linenumberstrue
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": {}
}


...

Column
width50%

Response

Code Block
languagejs
themeMidnight
firstline1
titleDELETE Accounts Response
linenumberstrue
HTTP/1.1 204 No Content
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d



Setup Account Request with All Permissions


Column
width50%

Request

Code Block
languagejs
themeMidnight
firstline1
titlePOST Account Requests Request
linenumberstrue
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": {}
}



Column
width50%

Response

Code Block
languagejs
themeMidnight
firstline1
titlePOST Account Requests Response
linenumberstrue
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
  }
}