Transaction import UI
Less than to read
This guide will walk you through the development requirements for a web-based product integrating with transaction import (v1). Before a user can utilise the transaction import funtionality they must have a bank account created in the Banking Service. For creation of a placeholder bank account follow the placeholder bank account guide.
Step 1. Obtain an access token
Before integrating with the Banking Service user interface, you need to integrated with the Authentication Service.
A JWT can be generated using the Authentication Service /accesstoken API endpoint (with requires a signature generated using the standard authorisation method). This JWT can then be provided as a Bearer token in the Authorisation header: ‘Bearer ‘. This JWT will need to be passed into the launch URL.
Step 2. Create the common UI URL
Create a transaction import (v1) UI launch URL. This will be used to launch the common UI within an iFrame inside a full dialogue modal window.
Required parameters
-
{Environment}
DEV → https://dev-money.sage.com
QA → https://qa-money.sage.com
PRE-PROD → https://pp-money.sage.com
SANDBOX → https://sandbox-money.sage.com
PROD → https://money.sage.com {route}
= the page to launch value is import-bank-transactions{JWT}
= the JWT from Service Fabric Authentication Service{lang}
= the language used for display of content translations [for example, en-us, en-uk, fr-fr, fr-ca, es-es]{UXSettings}
= UI experience settings. Preset options are :default, wpb-preview, web-iframe, web-popup, sage-desktop, intacct-banking. This field only changes the UI styling and does not effect any core funtionality.{bcApiRegion}
= region for Banking API call, defaults to US. Avialable options are are [eu, us].{countryCode}
= the default country code for bank listings, for example USA, GBR.{productname}
= Product the import bank transactions is initiated from.{bankAccountId}
= Bank’s account ID, for example, 59d4ca99-9da6-476f-ab11-8989e459239b{bankAccountName}
= Bank’s name, for example, Bank of America{currencyCode}
= possible value for currency code are: “USD”, “CAD”,”GBP”,”AUD”,”ZAR”,”MYR”,”EUR”,”BRL”.{accountRef}
= Account reference detail (this is a combination of sort code (UK), routing number (USA), IBAN.){xFrameDomain}
= Your product domain URL.
Step 3. Load the URLin a full screen dialogue modal
Create full screen dialogue modal https://brand.sage.com/d/NdbrveWvNheA/components#/containers/dialogs-full-screen and open that full screen dialogue modal when the user selects the transaction import button.
full screen dialogue modal code snippet
<!-- The Modal -->
<div id="dvFileImportV1" class="modal">
<!-- Modal content -->
<div class="modal-content">
<span class="close">×</span>
<div>
<iframe id="iframeWPBUIFileImportV1" height="850px" style="width: 100%;" src="" allow="fullscreen"></iframe>
</div>
</div>
</div>
Prepare File Import v1 UI URL & load into an iframe
const launchURL =
`${Environment}/xframe.html?apptokenroute=/${route}/${JWT}/
${lang}/{UXSettings}
&bcApiRegion=${bcRegion}
&defaultCountry=${countryCode}
&productname=${productName}
&bankAccountId=${bankAccountId}
&bankAccountName=${bankAccountName}
&accountRef=${bankAccountRef}
¤cyCode=${currencyCode}
&xFrameDomain=${xframeDomain}`;
const modal = document.getElementById("dvFileImportV1");
modal.style.display = "block";
document.getElementById('iframeWPBUIFileImportV1').src = launchURL;
Step 4. User follows the transaction import UI
4.1 Upload transactions
The 1st step allows the user to select their file type and upload their file through drag and drop or through the select file options. The user then needs to select the order the dates are displayed in their file and add a comment. This will allow them to identify the upload at a later point.
The system will attempt to upload the file with the backend API validating the content. If there are any errors or issues with the file or selected options (file type or date format), an appropriate error will be displayed to the user.
4.2 Verify transactions
When a file has been uploaded without error, the user will be asked to verify their transaction type. This allows the Banking Service to identify which transactions indicate money coming in and out of an accout. The user will be shown a single transaction and options to select if the transaction shows money coming into or going out of their account. Based on this selection, Banking Service will be able to display the rest of the transactions in the correct format.
4.3 Review transactions
The final step allows the user to review their transactions brought in from the uploaded file. All the transactions, bank account details, bank details and transaction date ranges will be displayed.
- Transactions without minus(-) will be displayed as type Money in (Credit)
- Transactions with minus(-) will be displayed as type Money out (Debit)
If there are any duplicate transactions (transactions imported previously for the same dates), a warning will be displayed to the user.
When reviewed, the user will select the import transactions button. This will notify the Banking Service to begin to process the import. When the file has been proccessed, the child UI will post back a JSON message to the parent product with details. The user is then redirected back to their product.
Step 5. Handle message returned from the iFrame
The Banking UI loading in the iFrame will post a message back to the parent window by calling the postMessage() method. To retrieve these messages back from the Banking UI you should implement the recieveMessage() method as demonstrated:
function receiveMessage(event) {
// Add security to ensure you trust the sender of this message
console.log("MY Data:", event);
}
window.addEventListener("message", receiveMessage, false);
The following is an example of a postback result from the Banking Service:
{"message":"active","data":{ "acccountId": "b0917c49-c765-4a30-a2f4-41fd552a84f7" }}
Step 6. Handle the closing of the iFrame
When you’ve received the post message confirming the transaction import, you should handle the closing of the iFrame and direct the user back to their product. You can then call the GET /transactions endpoint to get the newly uploaded set of transactions.
Recap
In this walkthrough we’ve covered how to load the transaction import UI with a bank account or placeholder bank account in an iFrame. We have also covered the steps the user would take when using the common UI to upload transactions and anything your solution would need to action.