Endpoints 

GET /accounts

A Third Party will be given the full list of accounts (the AccountId(s)) that the Customer has authorised the Third Party to access. The AccountId(s) returned can then be used to retrieve other resources for an account. The selection of authorised accounts happens only at the API Provider's interface.

The Third Party will use an access token associated with the Customer issued through an authorization code grant.

GET /accounts/{AccountId}

A Third Party may retrieve the account information resources for the AccountId (which is retrieved in the call to GET /accounts).

The Third Party will use an access token associated with the Customer issued through an authorization code grant.

Data Model

The OBReadAccount2 object will be used for the call to:

• GET /accounts/{AccountId}
• GET /accounts

Accounts - Resource Definition

The resource that represents the account to which credit and debit entries are made.

Each account resource will have a unique and immutable AccountId.

UML Diagram

Notes:

• The Account and Servicer blocks replicate what is used consistently throughout the Account Information APIs.
• This structure has been designed to:
  • Reflect the DebtorAccount and DebtorAgent (and similarly for CreditorAccount and CreditorAgent) structures in the Third Party use case
  • Having a SchemeName for the Account and Servicer blocks means we can be flexible to accommodate multiple types of accounts in the future
• SchemeName for PNZ is "BECSElectronicCredit"
• Where "BECSElectronicCredit" is specified as the SchemeName in the Account identification section, the Servicer section must not be populated and the identification field must be populated with a structured bank account number in the form of 12-1234-1234567-12 where:
  • the first two digits are the bank number, which tells us which bank the account resides with;
  • the next four digits indicate the branch number, which tells us which branch of that bank the account is domiciled;  
  • the next seven digits indicate the account number; and
  • the last two digits indicate the account number suffix.
• When the Third Party request contains an unsupported account SchemeName, API Provider must return a status code of 400 (Bad Request)
• When the Third Party request contains an unsupported currency, API Provider must return a status code of 400 (Bad Request)
• The SecondaryIdentification element can be used for the roll number for building societies

Permission Codes

The resource differs depending on the permissions (ReadAccountsBasic and ReadAccountsDetail) used to access resource. In the event the resource is accessed with both ReadAccountsBasic and ReadAccountsDetail, the most detailed level (ReadAccountsDetail) must be used.

• These objects must not be returned without the ReadAccountsDetail permission:
  • OBReadAccount1/Data/Account/Account
  • OBReadAccount1/Data/Account/Servicer
• If the ReadAccountsDetail is granted by the Customer:
  • OBReadAccount1/Data/Account/Account must be returned (1..n)
  • OBReadAccount1/Data/Account/Servicer may be returned if applicable to the account and API Provider (0..1)

Data Dictionary

GET /accounts 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

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    "Account": [
      {
        "AccountId": "22289",
        "Currency": "NZD",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Bills",
        "Account": {
          "SchemeName": "BECSElectronicCredit",
          "Identification": "12-1234-1234567-00",
          "Name": "Mr Kevin"
        }
      },
      {
        "AccountId": "31820",
        "Currency": "NZD",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Household",
        "Account": {
          "SchemeName": "BECSElectronicCredit",
          "Identification": "12-1234-1234567-25",
          "Name": "Mr Kevin"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

GET /accounts/22289 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

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    "Account": [
      {
        "AccountId": "22289",
        "Currency": "NZD",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Bills",
        "Account": {
          "SchemeName": "BECSElectronicCredit",
          "Identification": "12-1234-1234567-00",
          "Name": "Mr Kevin"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

GET /accounts 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

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    "Account": [
      {
        "AccountId": "22289",
        "Currency": "NZD",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Bills"
      },
      {
        "AccountId": "31820",
        "Currency": "NZD",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Household"
      }
    ]
  },
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts/"
  },
  "Meta": {
    "TotalPages": 1
  }
}