diff --git a/src/app-gocardless/README.md b/src/app-gocardless/README.md index d33cd21d97..23f8300e96 100644 --- 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 index 10b455d3d3..df300f5b9f 100644 --- 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 index d4ddc45a23..d05ee6e908 100644 --- 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 new file mode 100644 index 0000000000..09af98970d --- /dev/null +++ b/upcoming-release-notes/386.md @@ -0,0 +1,6 @@ +--- +category: Maintenance +authors: [tcrasset] +--- + +Prettify GoCardless Integration documentation \ No newline at end of file