Skip to content

Transaction import UI

  Less than to read


Transaction import UI v2 is now available, this document has now been deprecated.

This guide walks 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 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 ‘.

Step 2. Create the common UI URL

Create a transaction import (v1) UI launch URL. This is used to launch the common UI in an iFrame inside a full dialogue modal window.


QA Environment Sample URL:{JWT}/en-uk/default&defaultCountry=GBR&productname=SageAccounting&bankId=168efa64-5317-4607-b1d5-1e66eb8c3cda&bankAccountId=984b74e7-d7fd-4753-afbc-dcaadbb55b77&xFrameDomain=

Required parameters

  1. {Environment}
    DEV →
    QA →
    PRE-PROD →
    PROD →

  2. {route} = the page to launch value is import-bank-transactions.
  3. {JWT} = the JWT from Sage Network Platform Authentication Service.
  4. {lang} = the language used for display of content translations [for example, en-us, en-uk, fr-fr, fr-ca, es-es].
  5. {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 affect any core functionality.
  6. {bcApiRegion} = region for Banking API call, defaults to US. Available options are EU and US.
  7. {countryCode} = the default country code for bank listings. For example USA, GBR.
  8. {productname} = the product the import is initiated from.
  9. {bankAccountId} = the bank’s account ID, for example, 59d4ca99-9da6-476f-ab11-8989e459239b
  10. {bankAccountName} = the bank’s name, for example, Bank of America.
  11. {currencyCode} = the possible value for currency code are: “USD”, “CAD”,”GBP”,”AUD”,”ZAR”,”MYR”,”EUR”,”BRL”.
  12. {accountRef} = the account reference detail. This is a combination of sort code (UK), routing number (USA), and IBAN.
  13. {xFrameDomain} = your product domain URL.
  14. {bankId} = the identifier of the bank document that you’re topping up transactions from.

Step 3. Load the URL

Create a full screen dialogue modal and open it 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>
                <iframe id="iframeWPBUIFileImportV1" height="850px" style="width: 100%;" src="" allow="fullscreen"></iframe>

Prepare file import v1 UI URL and load into an iFrame

    const launchURL = 
    const modal = document.getElementById("dvFileImportV1"); = "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 a 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 can be used 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 – such as the file type or date format – an appropriate error is displayed to the user.

Image showing the first(a) screenshot of the UI. Image showing the first(b) screenshot of the UI.

4.2 Verify transactions

When a file has been uploaded without error, the user is asked to verify their transaction type. This allows the Banking Service to identify which transactions indicate money coming in and out of an account. The user is shown 1 transaction to identify whether it shows money coming into or going out of the account. Based on this, Banking Service will display the rest of the transactions in the correct format.

Image showing the second screenshot of the UI.

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 are 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.

Image showing the third screenshot of the UI.

When reviewed, the user will select the Import transactions button. This will notify Banking Service to begin 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 get messages back from the Banking UI, 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 postback results should be handled:

Import started
This message is sent when the processing of the file in Banking Service has started.

{ "message": "StartFo;e", "data": { "importId": "fileImportId", "bankId": "bankId", "bankAccountId": "bankAccountId", "fileName" : "fileName" }}

__Import confirmed__ <br>
This message is sent to confirm the import was successful. This occurs when the user selects the **finish** button on the choose transaction start date screen. You can store the 'fileImportId' for that specific 'bankAccountId'. This allows you to track the import to a specific account, company and organisation. 

{ "message": "ConfirmFileImport", "data": { "importId": "fileImportId", "bankId": "bankId", "bankAccountId": "bankAccountId"}}

Import cancelled
This is sent when a user chooses to cancel the import at any point during the import journey.

{ "message": "CancelFileImport", "data": {"ImportId": "importId"}}

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 transactions.


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.

Was this helpful?