Get transactions
Less than to read
When a customer has completed onboarding and connected their in-product bank account to bank feeds, you can start pulling their transactions into your product.
Transactions will be available after the account has been authorised and the bank, or 3rd party provider, has completed a transaction sync or push of transactions. The time for transactions to be available will depend on the authorisation process with the bank or 3rd party provider.
Offline processes where the customer needs to complete actions outside of the onboarding flow – like printing a form to send to their bank – may take serveral days to authorise. If the bank or 3rd party provider supports OAuth this process will be much quicker. Usually taking a few minutes.
Note: Transactions are not in real time and most banks and 3rd party providers will only provide new transactions 1 time a day. Banking Service will only provide transactions which have fully cleared the account. Any pending transactions will not be added as these can be removed or changed by the bank before they clear.
Prerequisites
Before developing this step you should have completed integration into the Banking Service onboarding flow either through the UI or with our API.
API flow diagram
Step 1. Obtain an access token
Before integrating with the Banking Service UI, integrate with the Authentication Service.
To work with Banking Service, you need an access token (JWT) from Authentication Service. The JWT is generated using the unique IDs of the organisation (organisationId) and company (companyId). This JWT can be provided as a bearer token for Banking Service requests through the authorisation header: ‘Bearer ‘.
Step 2. Retrieve transactions
The GET transactions endpoint retrieves transaction information for a given company and a given bank account.
If there are too many results to return, the bankTransactionList endIndex property will represent the ID of the last transaction returned.
GET /bankaccounts/{bankAccountId}/transactions
| Headers | Description |
|---|---|
x-application |
This is your application identifier which is generated from the Authentication Service. |
Authorization |
This is the bearer token returned from your request to the /accesstoken endpoint as described in Step 1. |
Content-Type |
This should be set as application/json. |
| Query Parameters | Description |
|---|---|
held |
Set held=true to include transaction that are held for processing in the accountant workflow. |
skip |
The index of the 1st item to return. Only valid if the held parameter is set to true. Only valid if the startIndex parameter is not included. |
top |
The number of items to return. Only valid if the held parameter is set to true. Only valid if the startIndex parameter is not included. Default: 100, maximum: 100, Minimum: 1 |
startIndex |
The index of the 1st transaction specified in the request, if the startIndex is not specified in the request the value will be 1. |
endIndex |
The index of the last transaction specified in the request, if the endIndex was not specified in the request the value will be 100 greater than the startIndex (inclusive) For example, startIndex 101 endIndex 200 |
pagesize |
An alternative to using endIndex. The default page size is 100 and the maximum page size is 1,000. |
Field descriptions
TransactionId– This identifier is unique in the scope of a bank account. It’s sequential and incremented for each transaction. It should not be assumed that gaps will not be present. There are scenarios where this could occur.TransactionType– At its most basic level a transaction is either a credit or debit. But when possible we capture the transaction type 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 account.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 aims to provide this consistency across credit cards.ReferenceNumber– Usually a number to identify the transaction adopted by the financial institution.transactionNarrative– Text descriptions of the transaction.Payee- Details of the person or organisation responsible for the payment.Category– This provides categorisation of transactions into multiple levels when the data source is from Plaid. This is not fully adopted by Banking Service.CheckNum- Check or cheque (or other reference) number. In the USA cheque usage is widespread due to banks charging for electronic payment. It is common for a business to drive their reconciliation process off check numbers.
Response
{
"bankAccount": {
"bankId": "b84a7cb2-4802-45e4-bac7-891e844bac7b",
"organisationId": "b7176e05-24f9-4f8c-892e-612d25adcd10",
"users": [],
"bankIdentifier": "11111111",
"accountIdentifier": "0123456789",
"accountType": "Checking",
"branchIdentifier": "branch_id",
"accountKey": "account_key",
"defaultCurrency": "USD",
"accountName": "Mr J Bloggs",
"clientAuthorisationToken": "A45FDE390A1FF209",
"status": "active",
"statusModifiedDate": "2016-07-15T17:53:35.000Z",
"statusReason": "standardFlow",
"statusReasonModifiedDate": "2019-08-20T00:00:00.000Z",
"lastTransactionId": 0,
"ledgerBalanceAmount": 0,
"ledgerBalanceDate": "2016-07-15T17:53:35.000Z",
"availableBalanceAmount": 0,
"availableBalanceDate": "2016-07-15T17:53:35.000Z",
"bankAccountId": "a097b480-ba11-4645-8426-9afd79c2b47e"
},
"bankTransactionList": {
"startIndex": 3,
"endIndex": 3,
"total": 5,
"prev": "https://pp.sagebankdrive.com/api/v1/organisations/6662e539-2d9c-4082-bfd7-bc8d95fff047/companies/42079ba0-68dc-4d71-ae1c-2acd87f0a010/bankaccounts/a097b480-ba11-4645-8426-9afd79c2b47e?startIndex=2&endIndex=2",
"first": "https://pp.sagebankdrive.com/api/v1/organisations/6662e539-2d9c-4082-bfd7-bc8d95fff047/companies/42079ba0-68dc-4d71-ae1c-2acd87f0a010/bankaccounts/a097b480-ba11-4645-8426-9afd79c2b47e?startIndex=1&endIndex=1",
"next": "https://pp.sagebankdrive.com/api/v1/organisations/6662e539-2d9c-4082-bfd7-bc8d95fff047/companies/42079ba0-68dc-4d71-ae1c-2acd87f0a010/bankaccounts/a097b480-ba11-4645-8426-9afd79c2b47e?startIndex=4&endIndex=4",
"last": "https://pp.sagebankdrive.com/api/v1/organisations/6662e539-2d9c-4082-bfd7-bc8d95fff047/companies/42079ba0-68dc-4d71-ae1c-2acd87f0a010/bankaccounts/a097b480-ba11-4645-8426-9afd79c2b47e?startIndex=5&endIndex=5",
"transactions": [
{
"transactionType": "DEBIT",
"transactionStatus": "posted",
"datePosted": "2016-06-16T20:12:01.356Z",
"dateUserInitiated": "2016-06-16T16:12:01.356Z",
"transactionAmount": 356.23,
"transactionId": 1,
"transactionHash": "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz",
"correctionId": "6cf2723d-3119-50a1-8a57-5ddd44d66f70",
"correctionAction": "replace",
"referenceNumber": 43543456,
"name": "Joe Bloggs",
"feedSource": "auto",
"payee": {
"payeeId": 34127698,
"address1": "Sage",
"city": "Newcastle",
"state": "Tyne & Wear",
"postalCode": "NE139AA"
},
"category": {
"topLevelCategory": "RETAIL",
"subCategory": "PETROL",
"categoryId": "CAT_ID"
},
"transactionNarrative": "Example narrative",
"accountsPostings": [
{
"createdBy": "[email protected]",
"grossAmount": 100,
"netAmount": 80,
"taxAmount": 20,
"accountantNarrative": "This is an account narrative",
"postingInstructions": [
{
"type": "supplier",
"code": "SUPP1",
"name": "Tesco PLC",
"status": "Account on hold",
"value": 100
}
]
}
],
"providerAdditionalFields": [
{
"name": "Extra1",
"value": 12585
}
],
"predictedActions": [
{
"predictionId": "b42fd2fc-7ba4-468d-82bc-22deb3197b66",
"score": 100,
"source": "User rule",
"rules": [
{
"type": "supplier",
"ruleId": "b42fd2fc-7ba4-468d-82bc-22deb3197b66",
"ruleRank": 1,
"match": "full"
}
],
"action": {
"type": "Direct Debit",
"reference": "Rent July",
"ruleAdditionalFields": [
{
"name": "auto-post",
"value": "true"
}
],
"accountsPostings": [
{
"createdBy": "[email protected]",
"grossAmount": 100,
"netAmount": 80,
"taxAmount": 20,
"accountantNarrative": "This is an account narrative",
"postingInstructions": [
{
"type": "supplier",
"userDefinedTypeName": "financials",
"code": "SUPP1",
"name": "Tesco PLC",
"status": "Account on hold",
"value": 100
}
]
}
]
}
}
]
}
]
}
}
BankAccount is not active
If you attempt to get transactions when a bank account is not in an active state you will recieve the following exception.
{
"$diagnoses": [
{
"$severity": "Error",
"$sdataCode": "ApplicationDiagnosis",
"$applicationCode": "InvalidState",
"$message": "BankAccount is not active"
}
]
}
Transaction narrative mapping between Provider API and Consumer API
| Provider API fields | Consumer API fields |
|---|---|
| narrative1 | narrative1 |
| narrative2 | narrative2 |
| description | name |
| referenceNumber | referenceNumber |
| extendedName | |
| payee.payeeDescription | payee.payeeId |
| checkNumber | checkNum |
Step 3. Implement paging
The default amount of transactions returned on a page is 100. The maximum amount is 1,000. You should implement paging to ensure you pull all outstanding transactions into the product for the customer. You can pass the start (startIndex) and end (endIndex) indices into the GET /transaction request to retrieve the next set of results. This can be continued until the next link is empty.
Step 4. Store the last transaction identifier
A product typically calls the transactions end point for each of its customer’s bank accounts either on demand or on a scheduled basis. This results in a lot of API traffic. The Banking Service are responsible for 100,000s of bank accounts.
Products are expected to keep this traffic to a minimum, only requesting transactions that they have not already received. This can be achieved by persisting the highest transactionId that you have stored. When you next call the GET /transactions endpoint you would pass in the latest transactionId + 1 as the start index.
For every bank account the transactionId will always begin at 1 and will increment for each new transaction added to Banking Service. There may be scenorios where Banking Service removes a transaction therefore creating a missing transactionId.
Step 5. Duplicate handling
When Banking Service gets transactions from a 3rd party or bank, it uses the unique transaction identifier from the source to validate if this transaction has already been added to for this Bank Account ID.
Banking Service will only persist transactions which have fully cleared the account and where the unique transaction idenitfier has not been previously been stored for this specific Bank Account ID.
In-product duplicates can occur when a customer disconnects their feed and reconnects to the same in-product account. Then, selecting a start date before the date of transactions they have previously downloaded.
Duplicates can also occur if a customer imports transactions into an account with an active feed as the unique transaction idenitfier from the import will not match the unique transaction idenitfier of the “same” transaction from the feed. Banking Service cannot detect duplicates in this scenario.
On rare occasions a 3rd party or bank many provide the same transactions with a different unique transaction idenitfier, in this scenario a Service Now ticket should be created.
Guides
Recap
In this walkthrough we have gone through the process of integrating directly with bank feeds functionality through the endpoints available on the Banking Service Consumer API.
What’s next?
Find out how to disconnect a bank account using the offboarding flow.