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.
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 accessAwaiting 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.
Frequency | Minimum number of similar transactions |
---|---|
Weekly | 8 |
Fortnightly | 6 |
Monthly | 3 |
Quarterly | 4 |
Yearly | 3 |
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.
Frequency | Maximum Number of Transactions |
---|---|
Weekly | 16 |
Fortnightly | 12 |
Monthly | 18 |
Quarterly | 12 |
Yearly | 6 |
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.
Updated 10 months ago
Have a look at the API reference or details about the accompanying webhooks