/
Transactions v3.0

Transactions v3.0

Sept 07, 2018

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

3.0-draft1

18-Apr-2018

OB R/W API Team

Initial draft for Version 3.0

3.0-draft3

May 21, 2018 

OB R/W API Team

Draft3 changes:

  • Updated OBReadTransaction2 to OBReadTransaction3 - with CurrencyExchange object replacing the EquivalentAmount object for currency exchange

  • Update data dictionary

3.0-draft4

Jun 4, 2018 

OB R/W API Team

Clarified use of Idempotency Key in endpoint table.

Updated the CurrencyExchange object to include the InstructedAmount.

3.0-draft5

Jun 13, 2018 

OB R/W API Team

Draft 5 changes:

  • Updated examples to change UTC to GMT to be in line with https://tools.ietf.org/html/rfc7231#page-66

  • Additional enumeration for CardInstrument/AuthorisationType of "ConsumerDevice"

  • Aligned running balance Balance/Type enumeration to the /balances endpoint

  • Additional optional field ChargeAmount - for transactions that have an embedded charge/fee in the Amount

  • P21 changes:

    • Internationalisation for the CreditorAgent and DebtorAgent objects.

      • SchemeName updated to Max40Text - so that additional schemes can be agreed and specified outside of the OB standard.

      • Name and PostalAddress as optional fields.

    • Internationalisation for the CreditorAccount and DebtorAccount objects.

      • SchemeName updated to Max40Text - so that additional schemes can be agreed and specified outside of the OB standard.

      • Identification updated to Max256Text - so that schemes that require an email address can be accommodated.

    • CreditorAccount/SchemeName and CreditorAccount/Identification set to optional - as these may not be populated by the ASPSP

    • DebtorAccount/SchemeName and DebtorAccount/Identification set to optional - as these may not be populated by the ASPSP

3.0-draft6/rc1

Jun 27, 2018 

OB R/W API Team

Draft6 Changes:

  • Clarified how the ReadPAN permission affects the resource.

  • Errata - updated relevant references to OBReadTransaction2 to OBReadTransaction3 (for changes in v3.0-draft3).

  • Updated definition of Name field in the CreditorAccount and DebtorAccount objects for clarity. Have specified usage that it is "The account name is the name or names of the account owner(s) represented at an account level. The account name is not the product name or the nickname of the account."

3.0-draft7

Jul 17, 2018 

OB R/W API Team

Draft 7 changes:

  • Added Usage Examples sub heading

3.0-RC2

Jul 19, 2018 

OB R/W API Team

No Change

3.0-RC3

Aug 6, 2018 

OB R/W API Team

No Change

3.0

Sep 7, 2018 

OB R/W API Team

This is the baseline version. No change from RC3.

Endpoints

Endpoints for the resource - and available methods.

Resource

HTTP Operation

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

Resource

HTTP Operation

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

1

transactions

GET

GET /accounts/{AccountId}/transactions

Mandatory

accounts

Authorization Code

No

Pagination

Filtering

 

OBReadTransaction3

2

transactions

GET

GET /transactions

Optional

accounts

Authorization Code

No

Pagination

Filtering

 

OBReadTransaction3

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

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 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:

    • OBReadTransaction3/Data/Transaction/TransactionInformation

    • OBReadTransaction3/Data/Transaction/Balance

    • OBReadTransaction3/Data/Transaction/MerchantDetails

    • OBReadTransaction3/Data/Transaction/CreditorAccount

    • OBReadTransaction3/Data/Transaction/DebtorAccount

  • If the ReadTransactionsDetail is granted by the PSU:

    • OBReadTransaction3/Data/Transaction/TransactionInformation may be returned if applicable to the transaction and ASPSP (0..1)

    • OBReadTransaction3/Data/Transaction/Balance may be returned if applicable to the transaction and ASPSP (0..1)

    • OBReadTransaction3/Data/Transaction/MerchantDetails may be returned if applicable to the transaction and ASPSP (0..1)

    • OBReadTransaction3/Data/Transaction/CreditorAccount may be returned if applicable to the transaction and ASPSP (0..1)

    • OBReadTransaction3/Data/Transaction/DebtorAccount may be returned if applicable to the transaction and ASPSP (0..1)

If the ReadPAN permission is granted by the PSU - the ASPSP may choose to populate the unmasked PAN - if the PAN is being populated in the response for these fields:

  • OBReadTransaction3/Data/Transaction/CreditorAgent/Identification

  • OBReadTransaction3/Data/Transaction/DebtorAccount/Identification

  • OBReadTransaction3/Data/Transaction/CardInstrument/Identification

Data Dictionary

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

OBReadTransaction3

 

OBReadTransaction3

 

OBReadTransaction3

 

 

Data

1..1

OBReadTransaction3/Data

 

OBReadDataTransaction3

 

 

Transaction

0..n

OBReadTransaction3/Data/Transaction

Provides further details on an entry in the report.

OBTransaction3

 

 

AccountId

1..1

OBReadTransaction3/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

OBReadTransaction3/Data/Transaction/TransactionId

Unique identifier for the transaction within an servicing institution. This identifier is both unique and immutable.

Max40Text

 

 

TransactionReference

0..1

OBReadTransaction3/Data/Transaction/TransactionReference

Unique reference for the transaction. This reference is optionally populated, and may as an example be the FPID in the Faster Payments context.

Max35Text

 

 

StatementReference

0..n

OBReadTransaction3/Data/Transaction/StatementReference

Unique reference for the statement. This reference may be optionally populated if available.

Max35Text

 

 

CreditDebitIndicator

1..1

OBReadTransaction3/Data/Transaction/CreditDebitIndicator

Indicates whether the transaction is a credit or a debit entry.

OBCreditDebitCode

Credit
Debit

 

Status

1..1

OBReadTransaction3/Data/Transaction/Status

Status of a transaction entry on the books of the account servicer.

OBEntryStatus1Code

Booked
Pending

 

BookingDateTime

1..1

OBReadTransaction3/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

OBReadTransaction3/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

OBReadTransaction3/Data/Transaction/TransactionInformation

Further details of the transaction.
This is the transaction narrative, which is unstructured text.

Max500Text

 

 

AddressLine

0..1

OBReadTransaction3/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

OBReadTransaction3/Data/Transaction/Amount

Amount of money in the cash transaction entry.

OBActiveOrHistoricCurrencyAndAmount

 

 

Amount

1..1

OBReadTransaction3/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

 

 

Currency

1..1

OBReadTransaction3/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}$

 

ChargeAmount

0..1

OBReadTransaction3/Data/Transaction/ChargeAmount

Transaction charges to be paid by the charge bearer.

OBActiveOrHistoricCurrencyAndAmount

 

 

Amount

1..1

OBReadTransaction3/Data/Transaction/ChargeAmount/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

 

 

Currency

1..1

OBReadTransaction3/Data/Transaction/ChargeAmount/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}$