mirror of
https://github.com/actualbudget/actual.git
synced 2026-03-11 12:43:09 -05:00
Prettify GoCardless Bank Integration README (#386)
This commit is contained in:
Tom Crasset
GitHub
@@ -1,47 +1,164 @@
|
||||
# Integration new bank
|
||||
|
||||
Find in [doc](https://docs.google.com/spreadsheets/d/1ogpzydzotOltbssrc3IQ8rhBLlIZbQgm5QCiiNJrkyA/edit#gid=489769432) what is id of bank which you want to integrate
|
||||
If the default bank integration does not work for you, you can integrate a new bank by following these steps.
|
||||
|
||||
Launch frontend and backend server
|
||||
1. Find in [this google doc](https://docs.google.com/spreadsheets/d/1ogpzydzotOltbssrc3IQ8rhBLlIZbQgm5QCiiNJrkyA/edit#gid=489769432) what is the identifier of the bank which you want to integrate.
|
||||
|
||||
Create new linked account selecting the institution which you are interested in.
|
||||
2. Launch frontend and backend server.
|
||||
|
||||
In the server logs you can find all required information to create class for
|
||||
your bank.
|
||||
3. In the frontend, create a new linked account selecting the institution which you are interested in.
|
||||
|
||||
Create new a bank class based on `app-gocardless/banks/sandboxfinance-sfin0000.js`. Name of the file and class should be
|
||||
created based on the ID of the integrated institution.
|
||||
This will trigger the process of fetching the data from the bank and will log the data in the backend. Use this data to fill the logic of the bank class.
|
||||
|
||||
Fill the logic of `normalizeAccount`, `normalizeTransaction`, `sortTransactions`, and `calculateStartingBalance` functions.
|
||||
You should do it based on the data which you found in the logs.
|
||||
4. Create new a bank class based on `app-gocardless/banks/sandboxfinance-sfin0000.js`.
|
||||
|
||||
Example logs which help you to fill:
|
||||
Name of the file and class should be created based on the ID of the integrated institution, found in step 1.
|
||||
|
||||
- `normalizeAccount` function:
|
||||
5. Fill the logic of `normalizeAccount`, `normalizeTransaction`, `sortTransactions`, and `calculateStartingBalance` functions.
|
||||
You do not need to fill every function, only those which are necessary for the integration to work.
|
||||
|
||||
```log
|
||||
Available account properties for new institution integration {
|
||||
account: '{"iban":"PL00000000000000000987654321","currency":"PLN","ownerName":"John Example","displayName":"Product name","product":"Daily account","usage":"PRIV","ownerAddressUnstructured":["POL","UL. Example 1","00-000 Warsaw"],"id":"XXXXXXXX-XXXX-XXXXX-XXXXXX-XXXXXXXXX","created":"2023-01-18T12:15:16.502446Z","last_accessed":null,"institution_id":"MBANK_RETAIL_BREXPLPW","status":"READY","owner_name":"","institution":{"id":"MBANK_RETAIL_BREXPLPW","name":"mBank Retail","bic":"BREXPLPW","transaction_total_days":"90","countries":["PL"],"logo":"https://cdn.nordigen.com/ais/MBANK_RETAIL_BREXCZPP.png","supported_payments":{},"supported_features":["access_scopes","business_accounts","card_accounts","corporate_accounts","pending_transactions","private_accounts"]}}'
|
||||
}
|
||||
```
|
||||
You should do it based on the data which you found in the logs.
|
||||
|
||||
- `sortTransactions` function:
|
||||
Example logs which help you to fill:
|
||||
|
||||
```log
|
||||
Available (first 10) transactions properties for new integration of institution in sortTransactions function {
|
||||
top10SortedTransactions: '[{"transactionId":"20220101001","bookingDate":"2022-01-01","valueDate":"2022-01-01","transactionAmount":{"amount":"5.01","currency":"EUR"},"creditorName":"JOHN EXAMPLE","creditorAccount":{"iban":"PL00000000000000000987654321"},"debtorName":"CHRIS EXAMPLE","debtorAccount":{"iban":"PL12345000000000000987654321"},"remittanceInformationUnstructured":"TEST BANK TRANSFER","remittanceInformationUnstructuredArray":["TEST BANK TRANSFER"],"balanceAfterTransaction":{"balanceAmount":{"amount":"448.52","currency":"EUR"},"balanceType":"interimBooked"},"internalTransactionId":"casfib7720c2a02c0331cw2"}]'
|
||||
}
|
||||
```
|
||||
- `normalizeAccount` function:
|
||||
|
||||
- `calculateStartingBalance` function:
|
||||
```log
|
||||
Available account properties for new institution integration {
|
||||
account: '{
|
||||
"iban": "PL00000000000000000987654321",
|
||||
"currency": "PLN",
|
||||
"ownerName": "John Example",
|
||||
"displayName": "Product name",
|
||||
"product": "Daily account",
|
||||
"usage": "PRIV",
|
||||
"ownerAddressUnstructured": [
|
||||
"POL",
|
||||
"UL. Example 1",
|
||||
"00-000 Warsaw"
|
||||
],
|
||||
"id": "XXXXXXXX-XXXX-XXXXX-XXXXXX-XXXXXXXXX",
|
||||
"created": "2023-01-18T12:15:16.502446Z",
|
||||
"last_accessed": null,
|
||||
"institution_id": "MBANK_RETAIL_BREXPLPW",
|
||||
"status": "READY",
|
||||
"owner_name": "",
|
||||
"institution": {
|
||||
"id": "MBANK_RETAIL_BREXPLPW",
|
||||
"name": "mBank Retail",
|
||||
"bic": "BREXPLPW",
|
||||
"transaction_total_days": "90",
|
||||
"countries": [
|
||||
"PL"
|
||||
],
|
||||
"logo": "https://cdn.nordigen.com/ais/MBANK_RETAIL_BREXCZPP.png",
|
||||
"supported_payments": {},
|
||||
"supported_features": [
|
||||
"access_scopes",
|
||||
"business_accounts",
|
||||
"card_accounts",
|
||||
"corporate_accounts",
|
||||
"pending_transactions",
|
||||
"private_accounts"
|
||||
]
|
||||
}
|
||||
}'
|
||||
}
|
||||
```
|
||||
|
||||
```log
|
||||
Available (first 10) transactions properties for new integration of institution in calculateStartingBalance function {
|
||||
balances: '[{"balanceAmount":{"amount":"448.52","currency":"EUR"},"balanceType":"forwardAvailable"},{"balanceAmount":{"amount":"448.52","currency":"EUR"},"balanceType":"interimBooked"}]',
|
||||
top10SortedTransactions: '[{"transactionId":"20220101001","bookingDate":"2022-01-01","valueDate":"2022-01-01","transactionAmount":{"amount":"5.01","currency":"EUR"},"creditorName":"JOHN EXAMPLE","creditorAccount":{"iban":"PL00000000000000000987654321"},"debtorName":"CHRIS EXAMPLE","debtorAccount":{"iban":"PL12345000000000000987654321"},"remittanceInformationUnstructured":"TEST BANK TRANSFER","remittanceInformationUnstructuredArray":["TEST BANK TRANSFER"],"balanceAfterTransaction":{"balanceAmount":{"amount":"448.52","currency":"EUR"},"balanceType":"interimBooked"},"internalTransactionId":"casfib7720c2a02c0331cw2"}]'
|
||||
}
|
||||
```
|
||||
- `sortTransactions` function:
|
||||
|
||||
Add new bank integration to `BankFactory` class in file `actual-server/app-gocardless/bank-factory.js`
|
||||
```log
|
||||
Available (first 10) transactions properties for new integration of institution in sortTransactions function
|
||||
{
|
||||
top10SortedTransactions: '[
|
||||
{
|
||||
"transactionId": "20220101001",
|
||||
"bookingDate": "2022-01-01",
|
||||
"valueDate": "2022-01-01",
|
||||
"transactionAmount": {
|
||||
"amount": "5.01",
|
||||
"currency": "EUR"
|
||||
},
|
||||
"creditorName": "JOHN EXAMPLE",
|
||||
"creditorAccount": {
|
||||
"iban": "PL00000000000000000987654321"
|
||||
},
|
||||
"debtorName": "CHRIS EXAMPLE",
|
||||
"debtorAccount": {
|
||||
"iban": "PL12345000000000000987654321"
|
||||
},
|
||||
"remittanceInformationUnstructured": "TEST BANK TRANSFER",
|
||||
"remittanceInformationUnstructuredArray": [
|
||||
"TEST BANK TRANSFER"
|
||||
],
|
||||
"balanceAfterTransaction": {
|
||||
"balanceAmount": {
|
||||
"amount": "448.52",
|
||||
"currency": "EUR"
|
||||
},
|
||||
"balanceType": "interimBooked"
|
||||
},
|
||||
"internalTransactionId": "casfib7720c2a02c0331cw2"
|
||||
}
|
||||
]'
|
||||
}
|
||||
```
|
||||
|
||||
Remember to add tests for new bank integration in
|
||||
- `calculateStartingBalance` function:
|
||||
|
||||
```log
|
||||
Available (first 10) transactions properties for new integration of institution in calculateStartingBalance function {
|
||||
balances: '[
|
||||
{
|
||||
"balanceAmount": {
|
||||
"amount": "448.52",
|
||||
"currency": "EUR"
|
||||
},
|
||||
"balanceType": "forwardAvailable"
|
||||
},
|
||||
{
|
||||
"balanceAmount": {
|
||||
"amount": "448.52",
|
||||
"currency": "EUR"
|
||||
},
|
||||
"balanceType": "interimBooked"
|
||||
}
|
||||
]',
|
||||
top10SortedTransactions: '[
|
||||
{
|
||||
"transactionId": "20220101001",
|
||||
"bookingDate": "2022-01-01",
|
||||
"valueDate": "2022-01-01",
|
||||
"transactionAmount": {
|
||||
"amount": "5.01",
|
||||
"currency": "EUR"
|
||||
},
|
||||
"creditorName": "JOHN EXAMPLE",
|
||||
"creditorAccount": {
|
||||
"iban": "PL00000000000000000987654321"
|
||||
},
|
||||
"debtorName": "CHRIS EXAMPLE",
|
||||
"debtorAccount": {
|
||||
"iban": "PL12345000000000000987654321"
|
||||
},
|
||||
"remittanceInformationUnstructured": "TEST BANK TRANSFER",
|
||||
"remittanceInformationUnstructuredArray": [
|
||||
"TEST BANK TRANSFER"
|
||||
],
|
||||
"balanceAfterTransaction": {
|
||||
"balanceAmount": {
|
||||
"amount": "448.52",
|
||||
"currency": "EUR"
|
||||
},
|
||||
"balanceType": "interimBooked"
|
||||
},
|
||||
"internalTransactionId": "casfib7720c2a02c0331cw2"
|
||||
}
|
||||
]'
|
||||
}
|
||||
```
|
||||
|
||||
6. Add new bank integration to `BankFactory` class in file `actual-server/app-gocardless/bank-factory.js`
|
||||
|
||||
7. Remember to add tests for new bank integration in
|
||||
|
||||
@@ -25,7 +25,7 @@ export default {
|
||||
/**
|
||||
* Following the GoCardless documentation[0] we should prefer `bookingDate`
|
||||
* here, though some of their bank integrations uses the date field
|
||||
* differently from what's describen in their documentation and so it's
|
||||
* differently from what's described in their documentation and so it's
|
||||
* sometimes necessary to use `valueDate` instead.
|
||||
*
|
||||
* [0]: https://nordigen.zendesk.com/hc/en-gb/articles/7899367372829-valueDate-and-bookingDate-for-transactions
|
||||
|
||||
@@ -25,7 +25,7 @@ export default {
|
||||
/**
|
||||
* Following the GoCardless documentation[0] we should prefer `bookingDate`
|
||||
* here, though some of their bank integrations uses the date field
|
||||
* differently from what's describen in their documentation and so it's
|
||||
* differently from what's described in their documentation and so it's
|
||||
* sometimes necessary to use `valueDate` instead.
|
||||
*
|
||||
* [0]: https://nordigen.zendesk.com/hc/en-gb/articles/7899367372829-valueDate-and-bookingDate-for-transactions
|
||||
|
||||
6
upcoming-release-notes/386.md
Normal file
6
upcoming-release-notes/386.md
Normal file
@@ -0,0 +1,6 @@
|
||||
---
|
||||
category: Maintenance
|
||||
authors: [tcrasset]
|
||||
---
|
||||
|
||||
Prettify GoCardless Integration documentation
|
||||
Reference in New Issue
Block a user