Transactions v2.0.0

Version Control

VersionDateAuthorComments
2.0-rc2Open Banking Read/Write API Team

This is the first Release Candidate with Split from One Page Specification.

  • Modified usage examples:
    • Removed references to x-jws-signature
    • Updated link URLs
    • Name-spaced AccountRequestIds in usage examples - as IntentIds are name-spaced in other usage examples. ASPSPs may construct the IntentId as they wish.
  • Additional guidance for ReadTransactionsDetail permission
2.0-rc3 Open Banking Read/Write API Team

Updates:

  • Added OBReadTransaction2/Data/Transaction/CreditorAccount and OBReadTransaction2/Data/Transaction/DebtorAccount to the ReadTransactionsDetail permission restrictions
  • Fixed OBExternalCardSchemeType1Code enumerations, and extended scheme names
  • Updated mandatory, conditional or optional as per Design Principles
2.0.0Open Banking Read/Write API TeamThis is the baseline version. No changes from v2.0-rc3.

Endpoints

Endpoints for the resource - and available methods.


Resource
HTTP Operation
Endpoint
Mandatory?
Scope
Grant Type
Idempotent
Parameters
Request Object
Response Object
1transactionsGETGET /accounts/{AccountId}/transactionsMandatoryaccountsAuthorization Code

Pagination

Filtering


OBReadTransaction2
2transactionsGET

GET /transactions

Optional

accountsAuthorization Code

Pagination

Filtering


OBReadTransaction2

GET /accounts/{AccountId}/transactions

An AISP may retrieve the transaction resource for a specific AccountId (which is retrieved in the call to GET /accounts).

GET /transactions

If an ASPSP has implemented the bulk retrieval endpoints - an AISP may optionally retrieve the transactions in bulk. 

This will retrieve the resources for all authorised accounts linked to the account-request.

Data Model

The OBReadTransaction2 object will be used for the call to:

  • GET /accounts/{AccountId}/transactions
  • GET /transactions
  • GET /accounts/{AccountId}/statements/{StatementId}transactions

Resource 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.

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 ASPSP 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 ASPSPs 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"
  • ASPSPs 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.

Transactions may be filtered based on their BookingDateTime using the fromBookingDateTime and toBookingDateTime parameters

The ASPSP must treat the following as valid input:

  • Non-working days (e.g. a Sunday or a Bank 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 ASPSP

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

Permission Codes

The resource differs depending on the permissions (ReadTransactionsBasic and ReadTransactionsDetail) used to access 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
  • If the ReadTransactionsDetail is granted by the PSU:
    • OBReadTransaction2/Data/Transaction/TransactionInformation may be returned if applicable to the transaction and ASPSP (0..1)
    • OBReadTransaction2/Data/Transaction/Balance may be returned if applicable to the transaction and ASPSP (0..1)
    • OBReadTransaction2/Data/Transaction/MerchantDetails may be returned if applicable to the transaction and ASPSP (0..1)
    • OBReadTransaction2/Data/Transaction/CreditorAccount may be returned if applicable to the transaction and ASPSP (0..1)
    • OBReadTransaction2/Data/Transaction/DebtorAccount may be returned if applicable to the transaction and ASPSP (0..1)

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadTransaction2
OBReadTransaction2
OBReadTransaction2

Data1..1OBReadTransaction2/Data
OBReadDataTransaction2

Transaction0..nOBReadTransaction2/Data/TransactionProvides further details on an entry in the report.OBTransaction2

AccountId1..1OBReadTransaction2/Data/Transaction/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

TransactionId0..1OBReadTransaction2/Data/Transaction/TransactionIdUnique identifier for the transaction within an servicing institution. This identifier is both unique and immutable.Max40Text

TransactionReference0..1OBReadTransaction2/Data/Transaction/TransactionReferenceUnique reference for the transaction. This reference is optionally populated, and may as an example be the FPID in the Faster Payments context.Max35Text

StatementReference0..nOBReadTransaction2/Data/Transaction/StatementReferenceUnique reference for the statement. This reference may be optionally populated if available.Max35Text

Amount1..1OBReadTransaction2/Data/Transaction/AmountAmount of money in the cash transaction entry.ActiveOrHistoricCurrencyAndAmount

Currency1..1OBReadTransaction2/Data/Transaction/Amount/CurrencyA 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}$
CreditDebitIndicator1..1OBReadTransaction2/Data/Transaction/CreditDebitIndicatorIndicates whether the transaction is a credit or a debit entry.OBCreditDebitCodeCredit
Debit

Status1..1OBReadTransaction2/Data/Transaction/StatusStatus of a transaction entry on the books of the account servicer.OBEntryStatus1CodeBooked
Pending

BookingDateTime1..1OBReadTransaction2/Data/Transaction/BookingDateTimeDate 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

ValueDateTime0..1OBReadTransaction2/Data/Transaction/ValueDateTimeDate 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

TransactionInformation0..1OBReadTransaction2/Data/Transaction/TransactionInformationFurther details of the transaction.
This is the transaction narrative, which is unstructured text.
Max500Text

AddressLine0..1OBReadTransaction2/Data/Transaction/AddressLineInformation that locates and identifies a specific address for a transaction entry, that is presented in free format text.Max70Text

BankTransactionCode0..1OBReadTransaction2/Data/Transaction/BankTransactionCodeSet of elements used to fully identify the type of underlying transaction resulting in an entry.OBBankTransactionCodeStructure1

Code1..1OBReadTransaction2/Data/Transaction/BankTransactionCode/CodeSpecifies the family within a domain.ExternalBankTransactionFamily1Code

SubCode1..1OBReadTransaction2/Data/Transaction/BankTransactionCode/SubCodeSpecifies the sub-product family within a specific family.ExternalBankTransactionSubFamily1Code

ProprietaryBankTransactionCode0..1OBReadTransaction2/Data/Transaction/ProprietaryBankTransactionCodeSet of elements to fully identify a proprietary bank transaction code.ProprietaryBankTransactionCodeStructure1

Code1..1OBReadTransaction2/Data/Transaction/ProprietaryBankTransactionCode/CodeProprietary bank transaction code to identify the underlying transaction.Max35Text

Issuer0..1OBReadTransaction2/Data/Transaction/ProprietaryBankTransactionCode/IssuerIdentification of the issuer of the proprietary bank transaction code.Max35Text

Balance0..1OBReadTransaction2/Data/Transaction/BalanceSet 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

Amount1..1OBReadTransaction2/Data/Transaction/Balance/AmountAmount of money of the cash balance after a transaction entry is applied to the account..ActiveOrHistoricCurrencyAndAmount

Currency1..1OBReadTransaction2/Data/Transaction/Balance/Amount/CurrencyA 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}$
CreditDebitIndicator1..1OBReadTransaction2/Data/Transaction/Balance/CreditDebitIndicatorIndicates whether the balance is a credit or a debit balance.
Usage: A zero balance is considered to be a credit balance.
OBCreditDebitCodeCredit
Debit

Type1..1OBReadTransaction2/Data/Transaction/Balance/TypeBalance type, in a coded form.OBBalanceType1CodeClosingAvailable
ClosingBooked
Expected
ForwardAvailable
Information
InterimAvailable
InterimBooked
OpeningAvailable
OpeningBooked
PreviouslyClosedBooked

MerchantDetails0..1OBReadTransaction2/Data/Transaction/MerchantDetailsDetails of the merchant involved in the transaction.OBMerchantDetails1

MerchantName0..1OBReadTransaction2/Data/Transaction/MerchantDetails/MerchantNameName by which the merchant is known.Max350Text

MerchantCategoryCode0..1OBReadTransaction2/Data/Transaction/MerchantDetails/MerchantCategoryCodeCategory code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.Min3Max4Text

EquivalentAmount0..1OBReadTransaction2/Data/Transaction/EquivalentAmountAmount of money to be transferred between the debtor and creditor, before deduction of charges, expressed in the currency of the debtor's account, and to be transferred into a different currency.

Usage : Currency of the amount is expressed in the currency of the debtor's account, but the amount to be transferred is in another currency. The debtor agent will convert the amount and currency to the to be transferred amount and currency, eg, 'pay equivalent of 100000 EUR in JPY'(and account is in EUR).
EquivalentAmount

Amount1..1OBReadTransaction2/Data/Transaction/EquivalentAmount/AmountAmount of money to be transferred between debtor and creditor, before deduction of charges, expressed in the currency of the debtor's account, and to be transferred in a different currency.

Usage : Currency of the amount is expressed in the currency of the debtor's account, but the amount to be transferred is in another currency. The first agent will convert the amount and currency to the to be transferred amount and currency, eg, 'pay equivalent of 100000 EUR in JPY'(and account is in EUR).
CurrencyAndAmount

Currency1..1OBReadTransaction2/Data/Transaction/EquivalentAmount/Amount/CurrencyCode 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". Valid currency codes are registered with the ISO 4217 Maintenance Agency, and consist of three contiguous letters.CurrencyCode
^[A-Z]{3,3}$
CurrencyOfTransfer1..1OBReadTransaction2/Data/Transaction/EquivalentAmount/CurrencyOfTransferSpecifies the currency of the to be transferred amount, which is different from the currency of the debtor's account.CurrencyCode
^[A-Z]{3,3}$
CreditorAgent0..1OBReadTransaction2/Data/Transaction/CreditorAgentFinancial institution servicing an account for the creditor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBReadTransaction2/Data/Transaction/CreditorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBReadTransaction2/Data/Transaction/CreditorAgent/IdentificationUnique and unambiguous identification of a financial institution or a branch of a financial institution.Max35Text

CreditorAccount0..1OBReadTransaction2/Data/Transaction/CreditorAccountUnambiguous identification of the account of the creditor, in the case of a debit transaction.OBCashAccount2

SchemeName1..1OBReadTransaction2/Data/Transaction/CreditorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification3CodeIBAN
PAN
SortCodeAccountNumber

Identification1..1OBReadTransaction2/Data/Transaction/CreditorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text

Name0..1OBReadTransaction2/Data/Transaction/CreditorAccount/NameName 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

SecondaryIdentification0..1OBReadTransaction2/Data/Transaction/CreditorAccount/SecondaryIdentificationThis 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

DebtorAgent0..1OBReadTransaction2/Data/Transaction/DebtorAgentFinancial institution servicing an account for the debtor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBReadTransaction2/Data/Transaction/DebtorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBReadTransaction2/Data/Transaction/DebtorAgent/IdentificationUnique and unambiguous identification of a financial institution or a branch of a financial institution.Max35Text

DebtorAccount0..1OBReadTransaction2/Data/Transaction/DebtorAccountUnambiguous identification of the account of the debtor, in the case of a crebit transaction.OBCashAccount2

SchemeName1..1OBReadTransaction2/Data/Transaction/DebtorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification3CodeIBAN
PAN
SortCodeAccountNumber

Identification1..1OBReadTransaction2/Data/Transaction/DebtorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text

Name0..1OBReadTransaction2/Data/Transaction/DebtorAccount/NameName 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

SecondaryIdentification0..1OBReadTransaction2/Data/Transaction/DebtorAccount/SecondaryIdentificationThis 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

CardInstrument0..1OBReadTransaction2/Data/Transaction/CardInstrumentSet of elements to describe the card instrument used in the transaction.OBTransactionCardInstrument1

CardSchemeName1..1OBReadTransaction2/Data/Transaction/CardInstrument/CardSchemeNameName of the card scheme.OBExternalCardSchemeType1CodeAmericanExpress
Diners
Discover
MasterCard
VISA

AuthorisationType0..1OBReadTransaction2/Data/Transaction/CardInstrument/AuthorisationTypeThe card authorisation type.OBExternalCardAuthorisationType1CodeContactless
None
PIN

Name0..1OBReadTransaction2/Data/Transaction/CardInstrument/NameName of the cardholder using the card instrument.Max70Text

Identification0..1OBReadTransaction2/Data/Transaction/CardInstrument/IdentificationIdentification assigned by an institution to identify the card instrument used in the transaction. This identification is known by the account owner, and may be masked.Max34Text

Enumerations

This section gives the definitions for enumerations used.

Code ClassName Definition 
OBBalanceType1CodeClosingAvailable Closing balance of amount of money that is at the disposal of the account owner on the date specified. 
OBBalanceType1CodeClosingBooked 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. 
OBBalanceType1CodeExpected 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. 
OBBalanceType1CodeForwardAvailable Forward available balance of money that is at the disposal of the account owner on the date specified. 
OBBalanceType1CodeInformation Balance for informational purposes. 
OBBalanceType1CodeInterimAvailable Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. 
OBBalanceType1CodeInterimBooked Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. 
OBBalanceType1CodeOpeningAvailable Opening balance of amount of money that is at the disposal of the account owner on the date specified. 
OBBalanceType1CodeOpeningBooked Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. 
OBBalanceType1CodePreviouslyClosedBooked 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. 
OBCreditDebitCodeCreditOperation is a credit
OBCreditDebitCodeDebitOperation is a debit
OBEntryStatus1CodeBookedBooked 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.
OBEntryStatus1CodePendingBooking 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.
OBExternalAccountIdentification2CodeIBANAn identifier used internationally by financial institutions to uniquely identify the account of a customer at a financial institution, as described in the latest edition of the international standard ISO 13616. "Banking and related financial services - International Bank Account Number (IBAN)".
OBExternalAccountIdentification2CodeSortCodeAccountNumberSort Code and Account Number - identifier scheme used in the UK by financial institutions to identify the account of a customer. The identifier is the concatenation of the 6 digit UK sort code and 8 digit account number.
The regular expression for this identifier is: ^[0-9]{6}[0-9]{8}$
OBExternalFinancialInstitutionIdentification2CodeBICFIValid 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.
OBExternalCardAuthorisationType1CodeContactlessCard authorisation was via Contactless.
OBExternalCardAuthorisationType1CodeNoneNo card authorisation was used.
OBExternalCardAuthorisationType1CodePINCard authorisation was via PIN.
OBExternalCardSchemeType1CodeAmericanExpressAmericanExpress scheme.
OBExternalCardSchemeType1CodeDinersDiners scheme.
OBExternalCardSchemeType1CodeDiscoverDiscover scheme.
OBExternalCardSchemeType1CodeMasterCardMasterCard scheme.
OBExternalCardSchemeType1CodeVISAVISA scheme.

Usage Examples

Specific Account

Request

Response

Bulk

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

Request

Response

No Access

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

Request

Response