Version | Date | Author | Comments |
---|---|---|---|
1.0.0 | 01 March 2019 | Payments NZ API Working Group | Baseline specification for Accounts resource |
Resource | Endpoint | Mandatory? | Scope | Grant Type | Idempotent | Parameters | Request Object | Response Object | |
---|---|---|---|---|---|---|---|---|---|
1 | accounts | GET /accounts | Mandatory | accounts | Authorization Code | Pagination | OBReadAccount1 | ||
2 | accounts | GET /accounts/{AccountId} | Mandatory | accounts | Authorization Code | OBReadAccount1 |
The first step for a Third Party after an account-request is authorised - is to call the GET /accounts endpoint. |
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.
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.
The OBReadAccount2 object will be used for the call to:
The resource that represents the account to which credit and debit entries are made.
Each account resource will have a unique and immutable AccountId.
Notes:
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.
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
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 | ||
AccountId | 1..1 | OBReadAccount2/Data/Account/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 | OBReadAccount2/Data/Account/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 | OBReadAccount2/Data/Account/AccountType | Specifies the type of account (personal or business). | OBExternalAccountType1Code | Business Personal | |
AccountSubType | 0..1 | OBReadAccount2/Data/Account/AccountSubType | Specifies the sub type of account (product family group). | OBExternalAccountSubType1Code | ChargeCard CreditCard CurrentAccount EMoney Loan Mortgage PrePaidCard Savings | |
Description | 0..1 | OBReadAccount2/Data/Account/Description | Specifies the description of the account type. | Max35Text | ||
Nickname | 0..1 | OBReadAccount2/Data/Account/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 | OBReadAccount2/Data/Account/Account | Provides the details to identify an account. | OBCashAccount2 | ||
SchemeName | 1..1 | OBReadAccount2/Data/Account/Account/SchemeName | Name of the identification scheme, in a coded form as published in an external list. | OBExternalAccountIdentification2Code | BECSElectronicCredit | |
Identification | 1..1 | OBReadAccount2/Data/Account/Account/Identification | Identification assigned by an institution to identify an account. This identification is known by the account owner. | Max34Text | ||
Name | 0..1 | OBReadAccount2/Data/Account/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 | OBReadAccount2/Data/Account/Account/SecondaryIdentification | This is secondary identification of the account, as assigned by the account servicing institution. This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination). | Max34Text | ||
Servicer | 0..1 | OBReadAccount2/Data/Account/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 | OBReadAccount2/Data/Account/Servicer/SchemeName | Name of the identification scheme, in a coded form as published in an external list. | OBExternalFinancialInstitutionIdentification2Code | BICFI | |
Identification | 1..1 | OBReadAccount2/Data/Account/Servicer/Identification | Unique and unambiguous identification of the servicing institution. | Max35Text |
This section gives the definitions for enumerations used.
Code Class | Name | Definition |
---|---|---|
OBExternalAccountIdentification2Code | 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:
|
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. |
The call to GET /accounts is the first step after an account-request is authorised. This will allow the Third Party to discover which accounts (and AccountId values) are associated with the authorisation of consent.
The ReadAccountsDetail permission has been granted.
Request
|
Response
|
A Third Party can also retrieve the account resource details specifically for AccountId 22289
The ReadAccountsDetail permission has been granted.
Request
|
Response
|
The ReadAccountsBasic permission has been granted.
|
|