1 Version Control
2 Definition
3 Endpoints
- 3.1 GET /accounts/{AccountId}/transactions
- 3.2 GET /transactions
4 Data Model
- 4.1 UML Diagram
- 4.2 Notes
- 4.3 Filtering
  - 4.3.1 Filtering Examples
- 4.4 Permission Codes
- 4.5 Data Dictionary
- 4.6 Enumerations
5 Usage Examples
- 5.1 Specific Account
  - 5.1.1 Request
    - 5.1.1.1 Get Account Transactions Request
  - 5.1.2 Response
    - 5.1.2.1 Get Account Transactions Response
- 5.2 Bulk
  - 5.2.1 Request
    - 5.2.1.1 Get Transactions Request
  - 5.2.2 Response
    - 5.2.2.1 Get Transactions Response
- 5.3 No Access
  - 5.3.1 Request
    - 5.3.1.1 GET Account Transactions Request
  - 5.3.2 Response
    - 5.3.2.1 GET Account Transactions Response

Version Control

Version	Date	Author	Comments

Version

Date

Author

Comments

2.0.0

Apr 30, 2020

Payments NZ API Working Group

Baseline specification for Beneficiaries resource

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
Definition of 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

A resource that describes a posting to an account that results in an increase or decrease to a balance.

For a specific date range - an account (AccountId) may have no transactions booked, or may have multiple transactions booked.

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

transactions

GET

GET /accounts/{AccountId}/transactions

Mandatory

accounts

Redirect Flow; or

Decoupled Flow

No

Pagination

Filtering

OBReadTransaction2

transactions

GET

GET /transactions

Optional

accounts

Redirect Flow; or

Decoupled Flow

No

Pagination

Filtering

OBReadTransaction2

GET /accounts/{AccountId}/transactions

The API endpoint allows a Third Party to retrieve the transactions for a specific AccountId (which is retrieved in the call to GET /accounts).

The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow).

GET /transactions

The API endpoint allows a Third Party to retrieve the transactions in bulk, if an API Provider has implemented the bulk retrieval endpoint.

The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow).
This will retrieve the transactions for all accounts linked to the account-access-consent.

Data Model

The OBReadTransaction2 object will be used for the call to:

GET /accounts/{AccountId}/transactions
GET /transactions

UML Diagram

Notes

The use of the term "Transaction" has been made consistently in the Transaction endpoint payload (instead of "Entry" which is the ISO20022 element name)
A DateTime element has been used instead of a complex choice element of Date and DateTime. Where time elements do not exist in API Provider systems - the time portion of the DateTime element will be defaulted to 00:00:00+00:00
The BookingDateTime has been set to mandatory - as all API Providers must provide this field for pagination and filtering. The BookingDateTime is the date the transaction is booked (or posted) and becomes immutable - which is not the date the transaction took place.
Either the BankTransactionCode (which is the ISO transaction code list), or ProprietaryBankTransactionCode, or both may be populated. While the expectation is that at least one of BankTransactionCode or ProprietaryBankTransactionCode are populated - we have decided not to enforce this behaviour in the payload structure - as this would require nesting elements, and introducing complex choice elements.
The BankTransactionCode (ISO) code-list is documented on the ISO20022 website: https://www.iso20022.org/external_code_list.page; and External Code Sets spreadsheet.
- The ISO 20022 BankTransactionCode Code and SubCode are specified as a 4 letter codes. However - the principle we have applied for the code lists is to have longer more descriptive codes.
- The BankTransactionCode Code and SubCode will be populated with the long form description of the ISO 20022 code, with delimiters removed. E.g., the Family Code "CNTR" has a description of "Counter Transactions" which is populated as "CounterTransactions"
API Providers must have the ability to provide transactions through APIs for a period that at least equals the period provided through their online channels.

Filtering

Limited support for filtering is provided on the transactions resource.

Name	Occurrence	Enhanced Definition	Class

Name	Occurrence	Enhanced Definition	Class
fromBookingDateTime	0..1	Specifies start date and time for filtering of the Transaction records on the Transaction/BookingDateTime field	ISODateTime
toBookingDateTime	0..1	Specifies end date and time for filtering of the Transaction records on the Transaction/BookingDateTime field.	ISODateTime

The API Provider must treat the following as valid input:

Non-working days (e.g. a Sunday or a Public holiday) or any other days on which no transactions are recorded
Dates that fall outside the range for which transaction information is provided through APIs
Dates that fall outside the range for which a consent authorisation is available
Timezone may be included in the filter request - but must be ignored by the API Provider

In the above situations, the API Provider must return data for the remaining valid period specified by the filter.

Filtering Examples

// All transactions from 1st Jan, 2015
GET /transactions?fromBookingDateTime=2015-01-01T00:00:00

// All transactions in 2016
GET /transactions?fromBookingDateTime=2016-01-01T00:00:00&toBookingDateTime=2016-12-31T23:59:59

// All transactions in a specific account up to 31-Mar-2017
GET /accounts/1/transactions?toBookingDateTime=2017-03-31T23:59:59

Permission Codes

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

These objects must not be returned without the ReadTransactionsDetail permission:
- OBReadTransaction2/Data/Transaction/TransactionInformation
- OBReadTransaction2/Data/Transaction/Balance
- OBReadTransaction2/Data/Transaction/MerchantDetails
- OBReadTransaction2/Data/Transaction/CreditorAccount
- OBReadTransaction2/Data/Transaction/DebtorAccount
- OBReadTransaction2/Data/Transaction/CreditorAgent
- OBReadTransaction2/Data/Transaction/DebtorAgent
If the ReadTransactionsDetail is granted by the Customer:
- OBReadTransaction2/Data/Transaction/TransactionInformation may be returned if applicable to the transaction and API Provider (0..1)
- OBReadTransaction2/Data/Transaction/Balance may be returned if applicable to the transaction and API Provider (0..1)
- OBReadTransaction2/Data/Transaction/MerchantDetails may be returned if applicable to the transaction and API Provider (0..1)
- OBReadTransaction2/Data/Transaction/CreditorAccount may be returned if applicable to the transaction and API Provider (0..1)
- OBReadTransaction2/Data/Transaction/DebtorAccount may be returned if applicable to the transaction and API Provider (0..1)
- OBReadTransaction2/Data/Transaction/CreditorAgent may be returned if applicable to the transaction and API Provider (0..1)
- OBReadTransaction2/Data/Transaction/DebtorAgent may be returned if applicable to the transaction and API Provider (0..1)

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBReadTransaction2		OBReadTransaction2		OBReadTransaction2
Data	1..1	OBReadTransaction2/Data		OBReadDataTransaction2
Transaction	0..n	OBReadTransaction2/Data/Transaction		OBTransaction2
AccountId	1..1	OBReadTransaction2/Data/Transaction/AccountId	A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.	Max40Text
TransactionId	0..1	OBReadTransaction2/Data/Transaction/TransactionId	Unique identifier for the transaction within an servicing institution. This identifier is both unique and immutable.	Max40Text
StatementReference	0..n	OBReadTransaction2/Data/Transaction/StatementReference	Unique reference for the statement. This reference may be optionally populated if available.	Max35Text
CreditDebitIndicator	1..1	OBReadTransaction2/Data/Transaction/CreditDebitIndicator	Indicates whether the transaction is a credit or a debit entry.	OBCreditDebitCode	Credit Debit
Status	1..1	OBReadTransaction2/Data/Transaction/Status	Status of a transaction entry on the books of the account servicer.	OBEntryStatus1Code	Booked Pending
BookingDateTime	1..1	OBReadTransaction2/Data/Transaction/BookingDateTime	Date and time when a transaction entry is posted to an account on the account servicer's books. Usage: Booking date is the expected booking date, unless the status is booked, in which case it is the actual booking date.	ISODateTime
ValueDateTime	0..1	OBReadTransaction2/Data/Transaction/ValueDateTime	Date and time at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit transaction entry. Usage: If transaction entry status is pending and value date is present, then the value date refers to an expected/requested value date. For transaction entries subject to availability/float and for which availability information is provided, the value date must not be used. In this case the availability component identifies the number of availability days.	ISODateTime
TransactionInformation	0..1	OBReadTransaction2/Data/Transaction/TransactionInformation	Further details of the transaction. This is the transaction narrative, which is unstructured text.	Max500Text
AddressLine	0..1	OBReadTransaction2/Data/Transaction/AddressLine	Information that locates and identifies a specific address for a transaction entry, that is presented in free format text.	Max70Text
Amount	1..1	OBReadTransaction2/Data/Transaction/Amount	Amount of money in the cash transaction entry.	OBActiveOrHistoricCurrencyAndAmount
Amount	1..1	OBReadTransaction2/Data/Transaction/Amount/Amount	A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.	ActiveCurrencyAndAmount_SimpleType		^\d{1,13}\.\d{1,5}$
Currency	1..1	OBReadTransaction2/Data/Transaction/Amount/Currency	A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".	ActiveOrHistoricCurrencyCode		^[A-Z]{3,3}$
TransactionReference	0..1	OBReadTransaction2/Data/Transaction/TransactionReference	Remittance information for use with BECSElectronicCredit payment scheme.	NZBECSRemittance1
CreditorName	1..1	OBReadTransaction2/Data/Transaction/TransactionReference/CreditorName	The Creditor's Name.	Max20Text
DebtorName	0..1	OBReadTransaction2/Data/Transaction/TransactionReference/DebtorName	The Debtor's Name.	Max20Text
CreditorReference	0..1	OBReadTransaction2/Data/Transaction/TransactionReference/CreditorReference	Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.	NZBECSReference1
Particulars	0..1	OBReadTransaction2/Data/Transaction/TransactionReference/CreditorReference/Particulars	Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.	Max12Text
Code	0..1	OBReadTransaction2/Data/Transaction/TransactionReference/CreditorReference/Code	Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.	Max12Text
Reference	0..1	OBReadTransaction2/Data/Transaction/TransactionReference/CreditorReference/Reference	Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.	Max12Text
DebtorReference	0..1	OBReadTransaction2/Data/Transaction/TransactionReference/DebtorReference	Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.	NZBECSReference1
Particulars	0..1	OBReadTransaction2/Data/Transaction/TransactionReference/DebtorReference/Particulars	Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.	Max12Text
Code	0..1	OBReadTransaction2/Data/Transaction/TransactionReference/DebtorReference/Code	Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.	Max12Text
Reference	0..1	OBReadTransaction2/Data/Transaction/TransactionReference/DebtorReference/Reference	Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.	Max12Text
BankTransactionCode	0..1	OBReadTransaction2/Data/Transaction/BankTransactionCode	Set of elements used to fully identify the type of underlying transaction resulting in an entry.	OBBankTransactionCodeStructure1
Code	1..1	OBReadTransaction2/Data/Transaction/BankTransactionCode/Code	Specifies the family within a domain.	ExternalBankTransactionFamily1Code
SubCode	1..1	OBReadTransaction2/Data/Transaction/BankTransactionCode/SubCode	Specifies the sub-product family within a specific family.	ExternalBankTransactionSubFamily1Code
ProprietaryBankTransactionCode	0..1	OBReadTransaction2/Data/Transaction/ProprietaryBankTransactionCode	Set of elements to fully identify a proprietary bank transaction code.	ProprietaryBankTransactionCodeStructure1
Code	1..1	OBReadTransaction2/Data/Transaction/ProprietaryBankTransactionCode/Code	Proprietary bank transaction code to identify the underlying transaction.	Max35Text
Issuer	0..1	OBReadTransaction2/Data/Transaction/ProprietaryBankTransactionCode/Issuer	Identification of the issuer of the proprietary bank transaction code.	Max35Text
Balance	0..1	OBReadTransaction2/Data/Transaction/Balance	Set of elements used to define the balance as a numerical representation of the net increases and decreases in an account after a transaction entry is applied to the account.	OBTransactionCashBalance
CreditDebitIndicator	1..1	OBReadTransaction2/Data/Transaction/Balance/CreditDebitIndicator	Indicates whether the balance is a credit or a debit balance. Usage: A zero balance is considered to be a credit balance.	OBCreditDebitCode	Credit Debit
Type	1..1	OBReadTransaction2/Data/Transaction/Balance/Type	Balance type, in a coded form.	OBBalanceType1Code	ClosingAvailable ClosingBooked Expected ForwardAvailable Information InterimAvailable InterimBooked OpeningAvailable OpeningBooked PreviouslyClosedBooked
Amount	1..1	OBReadTransaction2/Data/Transaction/Balance/Amount	Amount of money of the cash balance after a transaction entry is applied to the account.	OBActiveOrHistoricCurrencyAndAmount
Amount	1..1	OBReadTransaction2/Data/Transaction/Balance/Amount/Amount	A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.	ActiveCurrencyAndAmount_SimpleType		^\d{1,13}\.\d{1,5}$
Currency	1..1	OBReadTransaction2/Data/Transaction/Balance/Amount/Currency	A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".	ActiveOrHistoricCurrencyCode		^[A-Z]{3,3}$
MerchantDetails	0..1	OBReadTransaction2/Data/Transaction/MerchantDetails	Details of the merchant involved in the transaction.	OBMerchantDetails1
MerchantName	0..1	OBReadTransaction2/Data/Transaction/MerchantDetails/MerchantName	Name by which the merchant is known.	Max350Text
MerchantCategoryCode	0..1	OBReadTransaction2/Data/Transaction/MerchantDetails/MerchantCategoryCode	Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.	Min3Max4Text
CurrencyExchange	0..1	OBReadTransaction2/Data/Transaction/CurrencyExchange	Set of elements used to provide details of the currency exchange.	OBCurrencyExchange5
SourceCurrency	1..1	OBReadTransaction2/Data/Transaction/CurrencyExchange/SourceCurrency	Currency from which an amount is to be converted in a currency conversion.	ActiveOrHistoricCurrencyCode		^[A-Z]{3,3}$
TargetCurrency	0..1	OBReadTransaction2/Data/Transaction/CurrencyExchange/TargetCurrency	Currency into which an amount is to be converted in a currency conversion.	ActiveOrHistoricCurrencyCode		^[A-Z]{3,3}$
UnitCurrency	0..1	OBReadTransaction2/Data/Transaction/CurrencyExchange/UnitCurrency	Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP.	ActiveOrHistoricCurrencyCode		^[A-Z]{3,3}$
ExchangeRate	1..1	OBReadTransaction2/Data/Transaction/CurrencyExchange/ExchangeRate	Factor used to convert an amount from one currency into another. This reflects the price at which one currency was bought with another currency. Usage: ExchangeRate expresses the ratio between UnitCurrency and QuotedCurrency (ExchangeRate = UnitCurrency/QuotedCurrency).	BaseOneRate
ContractIdentification	0..1	OBReadTransaction2/Data/Transaction/CurrencyExchange/ContractIdentification	Unique identification to unambiguously identify the foreign exchange contract.	Max35Text
QuotationDate	0..1	OBReadTransaction2/Data/Transaction/CurrencyExchange/QuotationDate	Date and time at which an exchange rate is quoted.	ISODateTime
InstructedAmount	0..1	OBReadTransaction2/Data/Transaction/CurrencyExchange/InstructedAmount	Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.	OBActiveOrHistoricCurrencyAndAmount
Amount	1..1	OBReadTransaction2/Data/Transaction/CurrencyExchange/InstructedAmount/Amount	A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.	ActiveCurrencyAndAmount_SimpleType		^\d{1,13}\.\d{1,5}$
Currency	1..1	OBReadTransaction2/Data/Transaction/CurrencyExchange/InstructedAmount/Currency	A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".	ActiveOrHistoricCurrencyCode		^[A-Z]{3,3}$
CreditorAgent	0..1	OBReadTransaction2/Data/Transaction/CreditorAgent	Financial institution servicing an account for the creditor.	OBBranchAndFinancialInstitutionIdentification2
SchemeName	1..1	OBReadTransaction2/Data/Transaction/CreditorAgent/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalFinancialInstitutionIdentification2Code	BICFI
Identification	1..1	OBReadTransaction2/Data/Transaction/CreditorAgent/Identification	Unique and unambiguous identification of a financial institution or a branch of a financial institution.	Max35Text
CreditorAccount	0..1	OBReadTransaction2/Data/Transaction/CreditorAccount	Unambiguous identification of the account of the creditor, in the case of a debit transaction.	OBCashAccount2
SchemeName	1..1	OBReadTransaction2/Data/Transaction/CreditorAccount/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalAccountIdentification3Code	BECSElectronicCredit MaskedCardNumber
Identification	1..1	OBReadTransaction2/Data/Transaction/CreditorAccount/Identification	Identification assigned by an institution to identify an account. This identification is known by the account owner.	Max34Text
Name	0..1	OBReadTransaction2/Data/Transaction/CreditorAccount/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. OB: No name validation is expected for confirmation of payee.	Max70Text
SecondaryIdentification	0..1	OBReadTransaction2/Data/Transaction/CreditorAccount/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
DebtorAgent	0..1	OBReadTransaction2/Data/Transaction/DebtorAgent	Financial institution servicing an account for the debtor.	OBBranchAndFinancialInstitutionIdentification2
SchemeName	1..1	OBReadTransaction2/Data/Transaction/DebtorAgent/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalFinancialInstitutionIdentification2Code	BICFI
Identification	1..1	OBReadTransaction2/Data/Transaction/DebtorAgent/Identification	Unique and unambiguous identification of a financial institution or a branch of a financial institution.	Max35Text
DebtorAccount	0..1	OBReadTransaction2/Data/Transaction/DebtorAccount	Unambiguous identification of the account of the debtor, in the case of a crebit transaction.	OBCashAccount2
SchemeName	1..1	OBReadTransaction2/Data/Transaction/DebtorAccount/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalAccountIdentification3Code	BECSElectronicCredit MaskedCardNumber
Identification	1..1	OBReadTransaction2/Data/Transaction/DebtorAccount/Identification	Identification assigned by an institution to identify an account. This identification is known by the account owner.	Max34Text
Name	0..1	OBReadTransaction2/Data/Transaction/DebtorAccount/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	OBReadTransaction2/Data/Transaction/DebtorAccount/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
CardInstrument	0..1	OBReadTransaction2/Data/Transaction/CardInstrument	Set of elements to describe the card instrument used in the transaction.	OBTransactionCardInstrument1
CardSchemeName	1..1	OBReadTransaction2/Data/Transaction/CardInstrument/CardSchemeName	Name of the card scheme.	OBExternalCardSchemeType1Code	AmericanExpress Diners Discover MasterCard VISA
AuthorisationType	0..1	OBReadTransaction2/Data/Transaction/CardInstrument/AuthorisationType	The card authorisation type.	OBExternalCardAuthorisationType1Code	Contactless None PIN
Name	0..1	OBReadTransaction2/Data/Transaction/CardInstrument/Name	Name of the cardholder using the card instrument.	Max70Text
Identification	0..1	OBReadTransaction2/Data/Transaction/CardInstrument/Identification	Identification assigned by an institution to identify the card instrument used in the transaction. This identification is known by the account owner, and must be masked.	Max34Text

Enumerations

This section gives the definitions for enumerations used.

Code Class	Name	Definition

Code Class	Name	Definition
OBBalanceType1Code	ClosingAvailable	Closing balance of amount of money that is at the disposal of the account owner on the date specified.
OBBalanceType1Code	ClosingBooked	Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period.
OBBalanceType1Code	Expected	Balance, composed of booked entries and pending items known at the time of calculation , which projects the end of day balance if everything is booked on the account and no other entry is posted.
OBBalanceType1Code	ForwardAvailable	Forward available balance of money that is at the disposal of the account owner on the date specified.
OBBalanceType1Code	Information	Balance for informational purposes.
OBBalanceType1Code	InterimAvailable	Opening booked balance, plus today's credits, plus overdraft facility (if held) minus today debits, minus uncleared funds (note: uncleared funds equal the total of uncleared banked minus any uncleared funds amount held). This is the total available funds the customer is able to access. E.g. Interim Available Balance = Opening Booked Balance + Today's Credits + Overdraft Limit - Today's Debits - Uncleared Funds
OBBalanceType1Code	InterimBooked	This balance will be calculated at individual bank level as per existing internal definitions to ensure consistency for customers. What is included in the displayed balance may differ between banks. E.g. The balance of the account at a point in time / intraday / real time when requested, which may or may not include uncleared funds.
OBBalanceType1Code	OpeningAvailable	Opening balance of amount of money that is at the disposal of the account owner on the date specified.
OBBalanceType1Code	OpeningBooked	Opening Balance of an account at the end of batch processing that interest and fees are calculated on. This is the same balance as Previously Closed Booked Balance. Includes any uncleared funds, regardless of uncleared funds limits. E.g. balance after end of day process.
OBBalanceType1Code	PreviouslyClosedBooked	Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date.
OBCreditDebitCode	Credit	Operation is a credit
OBCreditDebitCode	Debit	Operation is a debit
OBEntryStatus1Code	Booked	Booked means that the transfer of money has been completed between account servicer and account owner Usage: Status Booked does not necessarily imply finality of money as this depends on other factors such as the payment system used, the completion of the end- to-end transaction and the terms agreed between account servicer and owner. Status Booked is the only status that can be reversed.
OBEntryStatus1Code	Pending	Booking on the account owner's account in the account servicer's ledger has not been completed. Usage: this can be used for expected items, or for items for which some conditions still need to be fulfilled before they can be booked. If booking takes place, the entry will be included with status Booked in subsequent account report or statement. Status Pending cannot be reversed.
OBExternalAccountIdentification3Code	BECSElectronricCredit	BECS Electronic Credit - identifier scheme used in NZ by financial institutions to identify the account of a customer. The identifier is bank-branch-account-suffix. The regular expression for this identifier is: ^[0-9]{2}-[0-9]{4}-[0-9]{7}-[0-9]{2}$
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.
OBExternalCardAuthorisationType1Code	Contactless	Card authorisation was via Contactless.
OBExternalCardAuthorisationType1Code	None	No card authorisation was used.
OBExternalCardAuthorisationType1Code	PIN	Card authorisation was via PIN.
OBExternalCardSchemeType1Code	AmericanExpress	AmericanExpress scheme.
OBExternalCardSchemeType1Code	Diners	Diners scheme.
OBExternalCardSchemeType1Code	Discover	Discover scheme.
OBExternalCardSchemeType1Code	MasterCard	MasterCard scheme.
OBExternalCardSchemeType1Code	VISA	VISA scheme.

Usage Examples

Specific Account

Retrieving transactions for a specific account.

Request

Get Account Transactions Request

GET /accounts/22289/transactions HTTP/1.1
Authorization: Bearer Az90SAOJklae
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 Account Transactions Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Transaction": [
      {
        "AccountId": "22289",
        "TransactionId": "123",        
        "TransactionReference": {
          "CreditorName": "Party being paid",
          "CreditorReference": {
            "Particulars": "Part1",
            "Code": "Code1",
            "Reference": "Ref1"
          },
          "DebtorName": "Party paying",
          "DebtorReference": {
            "Particulars": "Part2",
            "Code": "Code2",
            "Reference": "Ref2"
          }
        },
        "Amount": {
          "Amount": "10.00",
          "Currency": "NZD"
        },
        "CreditDebitIndicator": "Credit",
        "Status": "Booked",
        "BookingDateTime": "2017-04-05T10:43:07+00:00",
        "ValueDateTime": "2017-04-05T10:45:22+00:00",
        "TransactionInformation": "Cash from Aubrey",
        "BankTransactionCode": {
          "Code": "ReceivedCreditTransfer",
          "SubCode": "DomesticCreditTransfer"
        },
        "ProprietaryBankTransactionCode": {
          "Code": "Transfer",
          "Issuer": "ExampleBank"
        },
        "Balance": {
          "Amount": {
            "Amount": "230.00",
            "Currency": "NZD"
          },
          "CreditDebitIndicator": "Credit",
          "Type": "InterimBooked"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://api.examplebank.co.nz/open-banking-nz/v2.1/accounts/22289/transactions"
  },
  "Meta": {
    "TotalPages": 1,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }
}

Bulk

Retrieving transactions for all accounts linked to the account-access-consent.

None of the transactions included in the payload are Ecommerce transactions - so MerchantDetails are not included in the examples.

Request

Get Transactions Request

Response

Get Transactions Response

No Access

In this example - the Third Party does not have access to call the transactions endpoint. This will result in a 403 error.

Payments NZ API standards

Transactions v2.2.0

Version Control

Definition

Endpoints

GET /accounts/{AccountId}/transactions

GET /transactions

Data Model

UML Diagram

Notes

Filtering

Filtering Examples

Permission Codes

Data Dictionary

Enumerations

Usage Examples

Specific Account

Request

Get Account Transactions Request

Response

Get Account Transactions Response

Bulk

Request

Get Transactions Request

Response

Get Transactions Response

No Access

Request

GET Account Transactions Request

Response

GET Account Transactions Response