Transactions v2.3.3
- 1 Version Control
- 2 Definition
- 3 Endpoints
- 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.1 Request
- 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.2.1 Request
- 5.3 No Access
- 5.3.1 Request
- 5.3.1.1 GET Account Transactions Request
- 5.3.2 Response
- 5.3.1 Request
- 5.1 Specific Account
Version Control
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 | |
|---|---|---|---|---|---|---|---|---|---|
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 necessarily 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 |
|---|---|---|---|
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 |
|---|---|---|---|---|---|---|
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 | |
Status | 1..1 | OBReadTransaction2/Data/Transaction/Status | Status of a transaction entry on the books of the account servicer. | OBEntryStatus1Code | Booked | |
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. | 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. | ISODateTime | ||
TransactionInformation | 0..1 | OBReadTransaction2/Data/Transaction/TransactionInformation | Further details of the transaction. | 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. | OBCreditDebitCode | Credit | |
Type | 1..1 | OBReadTransaction2/Data/Transaction/Balance/Type | Balance type, in a coded form. | OBBalanceType1Code | ClosingAvailable | |
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 |