Transactions - v3.1.2

1. Overview
2. Endpoints
   1. GET /accounts/{AccountId}/transactions
   2. GET /transactions
3. Data Model
   1. Resource Definition
   2. UML Diagram
      1. Notes
   3. Filtering
      1. Filtering Examples
   4. Permission Codes
   5. Data Dictionary
4. Usage Examples
   1. Specific Account
      1. Get Account Transactions Request
      2. Get Account Transactions Response
   2. Bulk
      1. Get Transactions Request
      2. Get Transactions Response
   3. No Access
      1. GET Account Transactions Request
      2. GET Account Transactions Response

Overview

The transactions resource is used by an AISP to retrieve the transactions for a specific AccountId or to retrieve the transactions in bulk for account(s) that the PSU has authorised to access.

This resource description should be read in conjunction with a compatible Account Information Services API Profile.

Endpoints

Endpoints for the resource - and available methods.

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

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:
  • OBReadTransaction5/Data/Transaction/TransactionInformation
  • OBReadTransaction5/Data/Transaction/Balance
  • OBReadTransaction5/Data/Transaction/MerchantDetails
  • OBReadTransaction5/Data/Transaction/CreditorAgent
  • OBReadTransaction5/Data/Transaction/CreditorAccount
  • OBReadTransaction5/Data/Transaction/DebtorAgent
  • OBReadTransaction5/Data/Transaction/DebtorAccount
• If the ReadTransactionsDetail is granted by the PSU:
  • OBReadTransaction5/Data/Transaction/TransactionInformation may be returned if applicable to the transaction and ASPSP (0..1)
  • OBReadTransaction5/Data/Transaction/Balance may be returned if applicable to the transaction and ASPSP (0..1)
  • OBReadTransaction5/Data/Transaction/MerchantDetails may be returned if applicable to the transaction and ASPSP (0..1)
  • OBReadTransaction5/Data/Transaction/CreditorAgent may be returned if applicable to the transaction and ASPSP (0..1)
  • OBReadTransaction5/Data/Transaction/CreditorAccount may be returned if applicable to the transaction and ASPSP (0..1)
  • OBReadTransaction5/Data/Transaction/DebtorAgent may be returned if applicable to the transaction and ASPSP (0..1)
  • OBReadTransaction5/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:

• OBReadTransaction5/Data/Transaction/CreditorAccount/Identification
• OBReadTransaction5/Data/Transaction/DebtorAccount/Identification
• OBReadTransaction5/Data/Transaction/CardInstrument/Identification

Data Dictionary

Usage Examples

Specific Account

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 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

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": "Ref 1",
        "Amount": {
          "Amount": "10.00",
          "Currency": "GBP"
        },
        "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": "AlphaBank"
        },
        "Balance": {
          "Amount": {
            "Amount": "230.00",
            "Currency": "GBP"
          },
          "CreditDebitIndicator": "Credit",
          "Type": "InterimBooked"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v3.1/aisp/accounts/22289/transactions/"
  },
  "Meta": {
    "TotalPages": 1,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }
}

Bulk

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

Get Transactions Request

GET /transactions HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date:  Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Get 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": "Ref 123",
        "Amount": {
          "Amount": "10.00",
          "Currency": "GBP"
        },
        "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": "AlphaBank"
        },
        "Balance": {
          "Amount": {
            "Amount": "230.00",
            "Currency": "GBP"
          },
          "CreditDebitIndicator": "Credit",
          "Type": "InterimBooked"
        }
      },
      {
        "AccountId": "31820",
        "TransactionId": "567",
        "TransactionReference": "Ref 124",
        "Amount": {
          "Amount": "100.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Debit",
        "Status": "Booked",
        "BookingDateTime": "2017-05-02T14:22:09+00:00",
        "ValueDateTime": "2017-05-02T14:22:09+00:00",
        "TransactionInformation": "Paid the gas bill",
        "AddressLine": "Coventry",
        "BankTransactionCode": {
          "Code": "IssuedCreditTransfer",
          "SubCode": "AutomaticTransfer"
        },
        "ProprietaryBankTransactionCode": {
          "Code": "DirectDebit",
          "Issuer": "AlphaBank"
        },
        "Balance": {
          "Amount": {
            "Amount": "57.36",
            "Currency": "GBP"
          },
          "CreditDebitIndicator": "Debit",
          "Type": "InterimBooked"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v3.1/aisp/transactions"
  },
  "Meta": {
    "TotalPages": 1,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }
}

No Access

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

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 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

GET Account Transactions Response

HTTP/1.1 403 Forbidden 
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d