Regular Transaction Series

Prerequisites

You will need to log in to the API Gateway by retrieving an access token from the identity service. The moneyhub-api-client can be used to retrieve this, make sure the API client is configured correctly to do this. If you choose to not use the moneyhub-api-client, make sure you use the following scopes to go through this guide:

  • transactions:read:all
  • accounts:read
  • regular_transactions:read

Copy the access token returned and login to the API Gateway docs by putting Bearer ${accessToken} into the login modal.

API Reference

🚧

Manual Accounts

As it currently stands, regular transaction API will not work with manual accounts and transactions. You will need to create a connection with a financial provider and use the accounts within this connection.

🚧

Enrichment is not synchronus
The detection of regular transactions happens asynchronously to the rest of the sync as detailed in Use case 1:One time access or 2: Ongoing access

Awaiting the newRegularTransactions webhook is the easiest way of ensuring data is available.

What is a Regular Transaction Series

A regular transaction series is detected when the frequency of the payment, their description and amount coincide sufficiently to accurately predict that a real-world agreement is supported by this grouping of transactions. A number of similar transactions are required to give the confidence in detection, these numbers depend on the frequency and stated below.

FrequencyMinimum number of similar transactions
Weekly8
Fortnightly6
Monthly3
Quarterly4
Yearly3

Maximum Number of Transactions in a Series

There is a limit on the amount of transaction IDs that are returned in a regular transaction series. They depend on the frequency of the series and the limits are described in the table below.

FrequencyMaximum Number of Transactions
Weekly16
Fortnightly12
Monthly18
Quarterly12
Yearly6

Date predictions

Due to the nature of Direct Debits (can be over 4 working days) and card payments (within 3 working days) there is some tolerance in the predicted date. Where consistency is demonstrated the earliest and latest date will be the same.

Amount Predictions

Some series are for a regular amount (such as rent and mortgage), whereas some are for regular purposes (a varying mobile phone bill based on usage) where the amount may differ. Using previous transactions we predict the next payment value. We also provide the upper and lower limit of the prediction for reference

Series Statistics

The number of transactions in a series, identified gaps and date anomalies are powerful insights into the behaviour around the series.

  • The number of transactions in a series is a count of transactions detected.
  • The gaps are the number of times a payment has not been detected at the expected time.
  • Date anomalies are when a transaction is outside the usual cadence of the series.
  • Returned payments is a count where the payment is returned to the account shortly after leaving on the expected day, this is most likely due to insufficient funds in the account.

What’s Next

Have a look at the API reference or details about the accompanying webhooks