Version Control

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.

Endpoints

GET /accounts

The API endpoint allows a Third Party to retrieve, from an API Provider, the full list of accounts (the AccountId(s)) that a Customer has authorised the Third Party to access.

• The Third Party does this with the GET /accounts action.
• The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow). 
• The AccountId(s) returned from the API call can then be used to retrieve other resources for an account.
• The Customer is only able to select which of their accounts are linked to the account access consent at the API Provider's interface. 

GET /accounts/{AccountId}

The API endpoint allows a Third Party to retrieve, from an API Provider, a specific account (AccountId) resource that a Customer has authorised the Third Party to access.

• The Third Party does this with the GET /accounts/{AccountId} action.
• The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow). 
  

Data Model

The OBReadAccount2 object will be used for the call to:

• GET /accounts

The OBReadAccount3 object will be used for the call to:

• GET /accounts/{AccountId}

Both OBReadAccount2 and OBReadAccount3 use the OBAccount2 class. However, the OBReadAccount3 has a single OBAccount2 object within the Data object; whereas the OBReadAccount2 object allows for an array of OBAccount2 objects.

UML Diagram

OBAccount2

OBReadAccount2

OBReadAccount3

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.
• 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:
  • OBAccount2/Account
  • OBAccount2/Servicer
• If the ReadAccountsDetail is granted by the Customer:
  • OBAccount2/Account must be returned (1..1)
  • OBAccount2/Servicer may be returned if applicable to the account and API Provider (0..1)

If the ReadPAN permission is granted by the Customer, the API Provider may choose to populate the OBAccount2/Account/Identification with the unmasked PAN (if the PAN is being populated in the response).

Data Dictionary

OBAccount2

OBReadAccount2

OBReadAccount3

Enumerations

This section gives the definitions for enumerations used.

Usage Examples

Accounts - Bulk - Detail Permission

In this scenario, the ReadAccountsDetail permission has been granted.

The call to GET /accounts is the first step after an account-access-consent is authorised. This will allow the Third Party to discover which accounts (and AccountId values) are linked with the authorisation of consent. 

In this scenario, the ReadAccountsDetail permission has been granted.

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

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/v2.0/accounts"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Accounts - Specific Account - Detail Permission

A Third Party can also retrieve the account resource details specifically for AccountId 22289.

In this scenario, the ReadAccountsDetail permission has been granted.

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

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/v2.0/accounts/22289"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Accounts - Bulk - Basic Permission

In this scenario, the ReadAccountsBasic permission has been granted.

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

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/v2.0/accounts"
  },
  "Meta": {
    "TotalPages": 1
  }
}