Fetching transactions

Test transactions

Test transaction data can be obtained using one of these methods:

• Sage demo banks
• Plaid aggregator
• Yodlee aggregator

Sage demo banks

Our demo banks allow you to create test transactions.

For aggregators, Banking Service non-production environments are set up to work with the staging/sandbox environments of our 3rd party aggregators. They typically provide their own methods for obtaining test data.

Plaid aggregator

Accounts created through the Plaid aggregator automatically get populated with transactions.

Yodlee

Yodlee will only return sample transactions for a special bank named DAG Bank.

When performing a POST BankAccount call for an aggregator, the RequestedStartDate should be set to an early date to ensure capture of test transactions. It is recommended an early timestamp such as ‘2017-01-01T00:00:00.000Z’ is used.

GET Transactions API request

Full details of API Requests can be found in API reference but for specific illustration the API request to GET Transactions is:

GET /api/v1/organisations/{organisationId}/companies/{companyId}/bankaccounts/{bankAccountId}/transactions

A sample of the response body is as follows:

{
    "bankAccount": {
        …
    },
    "bankTransactionList": {
        "startIndex": 1,
        "endIndex": 100,
        "total": 145,
        "transactions": [
            {
                …
            },
            {
                …
            },
        ],
        "next": "https://",
        "last": "https://"
    }
}

Transaction properties

One of the goals of Banking Service is to provide consistent data and hide the idiosyncrasies of the varying data sources.

These are some of the key properties of a Bank Service transaction to illustrate how this is achieved at the data level:

TransactionID

This identifier is unique within the scope of a bank account. It is sequential and incremented for each transaction. It should not be assumed that gaps won’t be present, as scenarios do exist where this could occur.

TransactionType

A transaction is fundamentally either a credit or debit, but when possible transaction type is captured at a more detailed level; for example, other types can be XFER (transfer), DIRECTDEBIT or FEE.

DatePosted

The date the transaction was posted to the bank account and actioned; as opposed to the date the transaction occurred and was pending, which the user may also be familiar with from their internet banking.

TransactionAmount

The amount is negative in the case of debits and positive for credits. In terms of this value, a Debit can be considered as spending money from an account, and a Credit as adding money. The Banking Service also aims to provide this same consistency across credit cards.

ReferenceNumber

Usually a number to identify the transaction adopted by the financial institution.

Narrative properties

Textual descriptions of the transaction.

Payee object

Details of the person/organisation responsible for the payment, where available.

Category object

Not fully adopted, but provides categorisation of transaction into multiple levels when the data source is from Plaid.

CheckNum

Check/Cheque (or other reference) number. In the USA, cheque usage spread is widespread due to banks charging for electronic payment; it is therefore very common for a business to drive their reconciliation process using check numbers.

Paging

There are a number of details that can assist in requesting each of the individual pages of transactions.

The following optional query filter parameters can be used to control paging:

• startIndex
• endIndex
• pageSize

Links are also included as part of the transaction response body that support fetching neighbouring pages.

The lastTransactionId on a bank account record shows the highest transactionId captured for that Bank Account. This can be used in conjunction with the most recent transactionId that has been captured in a consuming applications last sync to drive paging.

The GET Transactions endpoint is expected to be used for each bank account either on demand or on a schedule. This generates a lot of traffic for the Banking Service API as the service is responsible for 100,000s of bank accounts. It is requested traffic is managed effectively by only requesting transactions that have no already been received.

Banking Service captures the last transaction retrieved on the lastFetchTransactionId property on the bank account but it is recommended the lastTransactionId is persisted within the consuming application so this can be tracked directly by a product should a sync fail to persist.

Additional information

• Banking Service bank accounts can also capture other financial accounts such as credit cards and loans.
• Banking Service only captures POSTED transactions which have cleared against a bank account. Should a data source also provide pending transactions they will be filtered out and ignored.
• When creating a bank account, its status is initially pending until it holds transactions, upon which, it will transition to active. In reality, this can take days for direct banks whilst the PDF form is sent to the bank. If an attempt to get transactions on a ‘pending’ bank account is made, a 409 status response and a message informing that the account is still pending will be returned.
• It is expected that transaction are received at least every 24-hours from Monday to Friday; this is potentially more frequent for an indirect bank account.
• The retention policy on bank account transactions highlights transactions held by Banking Service may be purged after they have been held for longer than 6 months.
• Banking Service stores balances against a bank account where they are available. The ledgerBalance property captures the balance purely based on posted transactions. The availableBalance property may consider transactions which have not yet cleared, and may include an overdraft facility.
• Transactions will typically be in the order in which they were posted. It should not be assumed, however, that this will always be the case.