1 Version Control
2 Definition
3 Endpoints
- 3.1 GET /accounts
- 3.2 GET /accounts/{AccountId}
4 Data Model
- 4.1 UML Diagram
  - 4.1.1 OBAccount2
  - 4.1.2 OBReadAccount2
  - 4.1.3 OBReadAccount3
- 4.2 Notes
- 4.3 Permission Codes
- 4.4 Data Dictionary
  - 4.4.1 OBAccount2
  - 4.4.2 OBReadAccount2
  - 4.4.3 OBReadAccount3
- 4.5 Enumerations
5 Usage Examples
- 5.1 Accounts - Bulk - Detail Permission
  - 5.1.1 Request
    - 5.1.1.1 GET Accounts Request
  - 5.1.2 Response
    - 5.1.2.1 GET Accounts Response
- 5.2 Accounts - Specific Account - Detail Permission
  - 5.2.1 Request
    - 5.2.1.1 GET Accounts Request
  - 5.2.2 Response
    - 5.2.2.1 GET Accounts Response
- 5.3 Accounts - Bulk - Basic Permission
  - 5.3.1 Request
    - 5.3.1.1 GET Accounts Request
  - 5.3.2 Response
    - 5.3.2.1 GET Accounts Response

Version Control

Version	Date	Author	Comments

Version

Date

Author

Comments

2.0.0

Apr 30, 2020

Payments NZ API Working Group

Baseline

2.1-draft1

Jun 15, 2020

@Gavin Wong (Unlicensed)

Updated:

Added MaskedCardNumber as new SchemeName enumeration for the account identification object in data dictionary as per https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/361955329 and https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/362020869
Added definition of the MaskedCardNumber
Usage Example version from v2.0 to v2.1

Removed:

ReadPAN permission as per https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/361922594

Definition

The resource that represents the account to which credit and debit entries are made. Each account will have a unique and immutable AccountId.

Endpoints

Resource	Endpoint	Mandatory?	Scope	Grant Type	Idempotency Key	Parameters	Request Object	Response Object

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

accounts

GET /accounts

Mandatory

accounts

Redirect Flow; or

Decoupled Flow

Pagination

OBReadAccount2

accounts

GET /accounts/{AccountId}

Mandatory

accounts

Redirect Flow; or

Decoupled Flow

OBReadAccount3

GET /accounts

A common action for a Third Party after an account-access-consent is authorised - is to call the GET /accounts endpoint to identify the accounts linked to the account-access-consent.

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) 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.
In the Account identification section:
- Where BECSElectronicCredit is specified as the SchemeName, 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.
- Where MaskedCardNumber is specified as the SchemeName, the Identification field must be populated with a masked credit card number. This masked credit card number is the card identification number exactly as it is presented to the Customer in the API Provider’s online portal. API Providers must ensure that any card related information returned through the API is compliant with PCI DSS requirements. API Providers must publish, on their developer portal, information on the format of their masked credit card number.
The SecondaryIdentification element can be used for the roll number for building societies

Permission Codes

The resource response differs depending on the permissions (ReadAccountsBasic and ReadAccountsDetail) used to access the 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)

Data Dictionary

OBAccount2

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
OBAccount2		OBAccount2	Provides the details to identify an account.	OBAccount2
AccountId	1..1	OBAccount2/AccountId	A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.	Max40Text
Currency	1..1	OBAccount2/Currency	Identification of the currency in which the account is held. Usage: Currency should only be used in case one and the same account number covers several currencies and the initiating party needs to identify which currency needs to be used for settlement on the account.	ActiveOrHistoricCurrencyCode	[A-Z]{3,3}
AccountType	0..1	OBAccount2/AccountType	Specifies the type of account (personal or business).	OBExternalAccountType1Code	Business Personal
AccountSubType	0..1	OBAccount2/AccountSubType	Specifies the sub type of account (product family group).	OBExternalAccountSubType1Code	ChargeCard CreditCard CurrentAccount EMoney Loan Mortgage PrePaidCard Savings
Description	0..1	OBAccount2/Description	Specifies the description of the account type.	Max35Text
Nickname	1..1	OBAccount2/Nickname	The nickname of the account, assigned by the account owner in order to provide an additional means of identification of the account.	Max70Text
Account	0..1	OBAccount2/Account	Provides the details to identify an account.	OBCashAccount2
SchemeName	1..1	OBAccount2/Account/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalAccountIdentification3Code	BECSElectronicCredit MaskedCardNumber
Identification	1..1	OBAccount2/Account/Identification	Identification assigned by an institution to identify an account. This identification is known by the account owner.	Max34Text
Name	0..1	OBAccount2/Account/Name	Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.	Max70Text
SecondaryIdentification	0..1	OBAccount2/Account/SecondaryIdentification	This is secondary identification of the account, as assigned by the account servicing institution.	Max34Text
Servicer	0..1	OBAccount2/Servicer	Party that manages the account on behalf of the account owner, that is manages the registration and booking of entries on the account, calculates balances on the account and provides information about the account.	OBBranchAndFinancialInstitutionIdentification2
SchemeName	1..1	OBAccount2/Servicer/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalFinancialInstitutionIdentification2Code	BICFI
Identification	1..1	OBAccount2/Servicer/Identification	Unique and unambiguous identification of the servicing institution.	Max35Text

OBReadAccount2

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern

Name	Occurrence	XPath	EnhancedDefinition	Class
OBReadAccount2		OBReadAccount2		OBReadAccount2
Data	1..1	OBReadAccount2/Data		OBReadDataAccount2
Account	0..n	OBReadAccount2/Data/Account	Unambiguous identification of the account to which credit and debit entries are made.	OBAccount2

OBReadAccount3

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern

Name	Occurrence	XPath	EnhancedDefinition	Class
OBReadAccount3		OBReadAccount3		OBReadAccount3
Data	1..1	OBReadAccount3/Data		OBReadDataAccount3
Account	1..1	OBReadAccount3/Data/Account	Unambiguous identification of the account to which credit and debit entries are made.	OBAccount2

Enumerations

This section gives the definitions for enumerations used.

Code Class	Name	Definition

Code Class	Name	Definition
OBExternalAccountIdentification3Code	BECSElectronicCredit	An identifier used to uniquely identify the account of a customer at a financial institution, structured 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.
OBExternalAccountIdentification3Code	MaskedCardNumber	Masked credit card number. This masked credit card number is the card identification number exactly as it is presented to the Customer in the API Provider’s online portal.
OBExternalFinancialInstitutionIdentification2Code	BICFI	Valid BICs for financial institutions are registered by the ISO 9362 Registration Authority in the BIC directory, and consist of eight (8) or eleven (11) contiguous characters.
OBExternalAccountSubType1Code	ChargeCard	Account sub-type is a Charge Card.
OBExternalAccountSubType1Code	CreditCard	Account sub-type is a Credit Card.
OBExternalAccountSubType1Code	CurrentAccount	Account sub-type is a Current Account.
OBExternalAccountSubType1Code	EMoney	Account sub-type is an EMoney.
OBExternalAccountSubType1Code	Loan	Account sub-type is a Loan.
OBExternalAccountSubType1Code	Mortgage	Account sub-type is a Mortgage.
OBExternalAccountSubType1Code	PrePaidCard	Account sub-type is a PrePaid Card.
OBExternalAccountSubType1Code	Savings	Account sub-type is a Savings.
OBExternalAccountType1Code	Business	Account type is for business.
OBExternalAccountType1Code	Personal	Account type is for personal.

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.

Request

GET Accounts Request

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

Response

GET Accounts Response

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

Accounts - Specific Account - Detail Permission

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

In this scenario, the ReadAccountsDetail permission has been granted.

Request

GET Accounts Request

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

Payments NZ API standards

Accounts v2.2.0

Version Control

Definition

Endpoints

GET /accounts

GET /accounts/{AccountId}

Data Model

UML Diagram

OBAccount2

OBReadAccount2

OBReadAccount3

Notes

Permission Codes

Data Dictionary

OBAccount2

OBReadAccount2

OBReadAccount3

Enumerations

Usage Examples

Accounts - Bulk - Detail Permission

Request

GET Accounts Request

Response

GET Accounts Response

Accounts - Specific Account - Detail Permission

Request

GET Accounts Request

Response

GET Accounts Response

Accounts - Bulk - Basic Permission

Request

GET Accounts Request

Response

GET Accounts Response