GET /accounts/{account_id}/transactions

In accordance with the guidance above, a typical Transaction History payload for a selected account (based on a GET /accounts/{account_id}/transactions call) takes the following form:

{

 "transactions": [{

     "id": "42909b155d4942299c39017686b5dc36",

      "type": "DEBIT",

      "status": "SUCCESS",

      "amount": {

          "currency": "EUR",

          "value": "100.0000"

      },

      "tokenId": "tt:3kFGtpEKHu8S2fJuEkb6YPnHZ4bJ2oUrYPCsJop68vCH:5zKcENpV",

      "tokenTransferId": "t:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",

      "createdAtMs": "1576788659686",

      "providerTransactionDetails": {}        // see note on provider metadata

 }],

 "offset": "pJUkL87QdDQu3mL9z1VK793RWasi19ERywLHP3L4uwjmEfcZPEPDU2R6rbDj6KbSogQcv",

 "status": "SUCCESSFUL_REQUEST"

}

Important query parameters are page.offset and page.limit. You can also filter the list by the query parameters startDate and endDate or transactionHistoryDays to pull transaction details for a specified number of days. The offset is the zero-based distance from the first item in the filtered collection to return. An offset of 0 starts at the very beginning of the filtered list. An offset of 49 starts the result from position 50 in the list and continues listing transactions until limit is reached. Hence, an offset of 50 with a limit of 100 returns filtered list items 51 through 151.

To continue retrieving the list in sequence, add 1 to the sum of offset and limit from the previous call (page.offsetpage.limit + 1) and set this as the new page.offset for the next call.

Refer to the Accounts section in Swagger Object and Field Definitions for additional details.

Key bank-dependent fields in the transactions object and their corresponding descriptions are listed in the following table.

Key Fields in the Bank's Account Transactions Response
Field Subfield Description
amount currency ISO currency code for the transaction
value Amount of the transaction valued in currency
creditorEndpoint account Specific information about the creditor's account, including bank, account features, and payment method
accountIdentifier One of four supported categories of bank and account identification – bbanClosedBasic Bank Account Number – represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. See https://www.mobilefish.com/services/bban_iban/bban_iban.php for help with BBAN conversion., gbDomesticClosedDomestic bank account identifier in the United Kingdom. Contains accountNumber and sortCode. The ISO country code is assumed to be GB., ibanClosedInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself., or tokenClosedOne of four supported categories of accountIdentifiers defined in the API's AccountDetails object. It identifies the user member's account by accountId and memberId.
bankId System-generated bank ID
customerData Address and legal name(s) related to the beneficiary account
description Description of the transaction
id Transaction ID
providerTransactionDetails Specific information regarding the transaction required by the respective Open Banking API standard adopted by the bank, such as the date-time of the transaction and pertinent instrument, business, and tax information, along with creditor and debtor identifiers for:

The account holder's MSISDNClosedMobile Station International Subscriber Directory Number – full phone number of a cellphone, including the country code and any area code or similar code issued by that country. Its maximum length is 15 digits. may be included by the provider if the transaction was initiated from a mobile device. However, the PANClosedPrimary Account Number – refers to a 14-, 15-, 16-, or even up to 19-digit number generated as a unique identifier designated for a primary account; also called payment card number and permanent card number. or a masked PAN are never included in the account details.

See note on provider metadata, as well as the protobuf reference or Swagger spec (under the Model tab) for object and field details.

status PENDING, PROCESSING, SUCCESS, PENDING_EXTERNAL_AUTHORIZATION, FAILURE_CANCELED, FAILURE_INSUFFICIENT_FUNDS, FAILURE_INVALID_CURRENCY, FAILURE_PERMISSION_DENIED, FAILURE_QUOTE_EXPIRED, FAILURE_INVALID_AMOUNT, FAILURE_INVALID_QUOTE, FAILURE_EXPIRED, FAILURE_DECLINED, FAILURE_GENERIC, SENT, INITIATED, STATUS_NOT_AVAILABLE

See Payment Status: Values and Meaning for status definitions

tokenId System-generated transfer token ID
tokenTransferId System-generated Transfer ID for the transaction
type Transaction type — DEBIT or CREDIT

 

Certain banks do not encode the transaction id returned in their response; in which case, it falls to the TPP itself to encode the transaction id in order to retrieve an individual transaction record in a subsequent access request. Token does not manipulate or alter data returned by the bank.

For all calls, field values in the response are populated based on data returned by the bank. Field values that are not populated in a response were not provided by the bank.

Consistent with the request-response structure discussed above, the API also supports information access to standing order information (GET /accounts/{account_id}/standing-orders/{standing_order_id}), along with a specific account's established transfer destinations (GET /accounts/{account_id}/transfer-destinations) to fetch the IBANClosedInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself..

When requesting access to a user's bank account information, it's important to keep in mind that Token doesn’t persist request data on its side. The requested information sent by the bank to the TPPClosedThird-Party Provider – an authorised online service provider introduced as part of Open Banking. TPPs exist outside of the account holder’s relationship with their bank but may be involved in transactions carried out by the user. is data mapped to a standard set of fields exposed by Token's API. Because it is not a mandatory field, some banks may choose not to return the transaction id in response to a transaction retrieval request, which can pose a challenge to the TPP when is comes to reconciling the information received in one request with updated information received in response to a subsequent request.

Token recommends building your own transaction reconciliation logic to handle the updating of transactions in between access requests. This reconciliation logic should be based on a combination of transaction id (if present), transaction date, transaction amount, transaction description, and the transaction account number.

Payee Information. Submission and return of payee information is not supported by all banks. When supported, and based on the standard adopted by the bank, creditor account (payee) information (legal name and/or address) is included in customerData within providerTransactionDetails for single transactions. When included in the request, payee information is available in the response, regardless of the API standard adopted by the bank; typically, however, the following guidelines apply:

Note: For all GET /account and GET /accounts endpoints, please ensure that you request permission for each desired endpoint — ACCOUNTS, BALANCES, TRANSACTIONS, and/or TRANSFER_DESTINATIONS — in the accessBody of your token request.

* * * *

Remember, you can add customer tracking headers — customer-initiated (boolean), token-customer-ip-address, token-customer-device-id — to GET /accounts, GET /accounts/{account_id}/balance, and GET /accounts/{account_id}/transactions calls to let the bank know that a particular API call was initiated by the PSUClosedPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both.. This may be useful in circumnavigating bank restrictions that impose a 4-times-a-day (i.e., the same 24-hour period) access limit on the same AISPClosedAccount Information Service Provider – a TPP authorised to access consumer or business account data from the account holder's financial institutions with the account holder's explicit consent. in accordance with RTS regulationsClosedRegulatory Technical Standard – detailed specifications to achieve the strict security requirements for payment service providers in the EU..

For example:

-header 'customer-initiated:true'\

-header 'token-customer-ip-address:127.0.0.1'\

-header 'token-customer-device-id:Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0:'

See Common Request Headers for information on other request headers.

Please refer to the API's Swagger Object and Field Definitions and Swagger Specification for additional details on all of the above.