Bank rules
Less than to read
Bank rules allow customers to create automated rules to categorise imported bank transactions in their Sage solution. This simplifies the users reconciliation process as they can often have thousands of transactions to action.
In the bank reconciliation feature of Sage products, 2 actions typically apply against transactions supplied by bank feeds:
- The bank transaction is found to match an existing transaction in the accounting product and is considered reconciled.
- If the transaction is not found in the company’s accounts, the user is can create an accounting transaction for it.
The Banking Service provides a facility for recognising banking transactions and suggests how a transaction in the Sage product should be created. This is achieved by allowing consumers to create rules through Banking Service, facilitating the identification of transaction types. When Banking Service recieves transactions, these rules are applied with user-suggested actions.
Note: Rules can only be applied to transactions in the Banking Service. These are transactions that have either been pulled through by a connected bank feed or manually imported through the Banking Service transaction import capability.
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 ‘.
2. Create a bank rule
This endpoint supports POST, GET, PUT, PATCH and DELETE operations.
POST /bankaccounts/{bankAccountId}/rules
| 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. |
Request Body (Example)
{
"ruleName": "New rule 1",
"ruleConditions": [{
"ruleField": "transactionAmount",
"ruleOperation": "gt",
"ruleCriteria": "10"
}],
"ruleAdditionalFields": [],
"ruleActions": [{
"splitPercentage": 50,
"accountantNarrative": "narrative 1",
"accountsPostings": [{
"type": "Main supplier",
"code": "SUPP1"
}]
}, {
"splitPercentage": 100,
"accountantNarrative": "narrative 2",
"accountsPostings": [{
"type": "Account 2",
"code": "ACC2"
}]
}]
}
3. Reprocess transactions
Rules are applied when transactions are received in Banking Service. So consumers can define rules and apply them during reconciliation, Banking Service provides a reprocess endpoint to trigger the rules to be ran against transactions on demand. This is done using the reprocesstransactions endpoint.
The endpoint takes a collection of transactionIDs to reprocess the rules, and starts the operation on the server; returning a URL to poll for progress.
POST /bankaccounts/{bankAccountId}/reprocesstransactions
| 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. |
Request body (example)
{
"transactionIds": [
1,
2,
3,
4,
7,
8,
104
]
}
Response (example)
{
"requestId": "00000000-0000-0000-0000-000000000001",
"pollRoute": "https://pp.sagebankdrive.com/api/v1/organisations/11111111-0000-0000-0000-000000000000/companies/22222222-0000-0000-0000-000000000000/bankAccounts/33333333-0000-0000-0000-000000000000/reprocesstransactions?requestId=00000000-0000-0000-0000-000000000001",
"pollPeriod": 1000
}
4. Get reprocessed transactions
The GET /reprocesstransactions endpoint is used as the polling route; on completion returning the updated transactions with the rules applied.
GET /{reprocessTransactionsPollRoute}
| 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. |
Request body (example)
{
"transactionIds": [1]
}
Response (example)
{
"transactions": [
{
"transactionType": "CREDIT",
"transactionStatus": "pending",
"datePosted": "2019-08-24",
"dateUserInitiated": "2019-08-24",
"dateFundsAvailable": "2019-08-24",
"transactionAmount": 0,
"transactionId": 0,
"transactionHash": "string",
"correctionId": "c0b4107d-3c95-4de0-af74-9b0e25bb771f",
"correctionAction": "REPLACE",
"serverTransactionId": "string",
"checkNum": "string",
"referenceNumber": "string",
"name": "string",
"payee": {
"address1": "string",
"address2": "string",
"address3": "string",
"city": "string",
"state": "string",
"postalCode": "string",
"country": "string",
"payeeId": "string",
"phoneNumber": "string",
"payeeBankId": "string",
"payeeAccountId": "string"
},
"extendedName": "string",
"narrative1": "string",
"narrative2": "string",
"currency": "string",
"coordinates": {
"lat": 0,
"long": 0
},
"category": {
"topLevelCategory": "string",
"subCategory": "string",
"categoryId": 0,
"standardIndustrialCode": "string"
},
"heldTransaction": true,
"transactionNarrative": "string",
"accountsPostings": [
{
"createdBy": "string",
"grossAmount": 0,
"netAmount": 0,
"taxAmount": 0,
"accountantNarrative": "string",
"postings": [
{
"type": "string",
"code": "string",
"name": "string",
"status": "string",
"value": null
}
]
}
],
"providerAdditionalFields": [
{
"name": "string",
"value": "string"
}
],
"predictedActions": [
{
"predictedId": "string",
"score": 0,
"source": "string",
"rules": [
{
"ruleId": "string",
"ruleRank": 0,
"match": "string"
}
],
"actions": {
"type": "string",
"reference": "string",
"ruleAdditionalFields": [
{
"name": "string",
"value": "string"
}
],
"accountsPostings": [
{
"createdBy": "string",
"grossAmount": 0,
"netAmount": 0,
"taxAmount": 0,
"accountantNarrative": "string",
"postingInstructions": [
{}
]
}
]
}
}
],
"feedSource": "auto"
}
]
}
5. Amending a rule
Rules can be amended using the PATCH /rules endpoint by providing the rule identifier and the updated fields to amend. It is also possible to update a rule using the put /rules endpoint by passing the complete rule in the request body.
PATCH /bankaccounts//rules/{ruleid}
| 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. |
Request body (example)
{
"ruleName": "Updated rule name"
}
6. Deleting a rule
You can delete a rule using the DELETE /rules endpoint by providing the rule identifier.
DELETE /bankaccounts//rules/{ruleid}
| 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. |
7. Restoring rules
When an account is disconnected all rules associated to the bank account ID will be placed in a disconnected state. If the user chooses to reconnect their in-product bank account to bank feeds these rules will not be reapplied.
Users should be given an option to recover rules and reapply them to the reconnected feed. This is done by calling the rules endpoint on the company for any previously disconnected rules.
Guides
Recap
In this walkthrough we have looked at how a consuming application would integrate bank rules into their solution.
What’s next?
Understand how rule-matching works along with the available fields and operations. Find out more about rule-matching.