Prettify GoCardless Bank Integration README (#386)

actualbudget · Jul 4, 2024 · 1da9c82 · 1da9c82
1 parent 2006d88
commit 1da9c82
Show file tree

Hide file tree

Showing 4 changed files with 156 additions and 33 deletions.
diff --git a/src/app-gocardless/README.md b/src/app-gocardless/README.md
@@ -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
diff --git a/src/app-gocardless/banks/sandboxfinance-sfin0000.js b/src/app-gocardless/banks/sandboxfinance-sfin0000.js
@@ -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

diff --git a/src/app-gocardless/banks/spk-karlsruhe-karsde66.js b/src/app-gocardless/banks/spk-karlsruhe-karsde66.js
@@ -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

diff --git a/upcoming-release-notes/386.md b/upcoming-release-notes/386.md
@@ -0,0 +1,6 @@
+---
+category: Maintenance
+authors: [tcrasset]
+---
+
+Prettify GoCardless Integration documentation