Skip to content

Reauthentication UI

  Less than to read

This guide walks through the development requirements for a web-based product integrating with bank feeds UI for reauthentication.


Reauthentication through the UI is the preferred integration method. This is because we have already handled the complexity of the reauthentication flow for different connections. It also reduces the need for future maintenance when there are brand or logo changes. These are managed centrally by the Sage Network Platform team

API flow diagram

Flow diagram displaying the reauthorisation flow

Step 1. Check account status

When calling the get transactions endpoint, you should check the status field on the bankAccount object returned. If the account status is set to authRequired, begin the reauthentication flow for this account.


Note: The bank is in control of when an account should be set to authRequired. Reauthentication could be set due to user security settings, a change to the authentication details or because multi-factor authentication has been enabled.

Step 2. 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 3. Create the common UI URL

Create a bank feeds UI launch URL. This will launch the common UI in an iFrame inside a full dialogue modal window.


QA Environment Sample URL:{JWT}/en-uk/default&defaultCountry=GBR&bankAccountId=984b74e7-d7fd-4753-afbc-dcaadbb55b77&xFrameDomain=

Required parameters

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

  2. {route} = the value to launch bank feeds reauthentication is banking-cloud_reauth.
  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} = 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), IBAN.
  13. {xFrameDomain} = the product domain URL. This needs to match the domain which is on the allowlist with your product identifier.
  14. {dateFormat} = regional date format to use, for example, DD%2FMM%2FYYYY.
  15. {multipleAccounts} = allow the setup of multiple accounts. Set to true or false. The default is true.
  16. {allowCountrySelection} = display country selection options. Set to y or n. The default is y.
  17. {UiRedirectUrlOnCompletion} = the URL to redirect the user to when onboard is complete.

Step 4. Load the URL

Create full screen dialogue modal and open it when the user selects transaction import button.

Full screen modal dialog 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;

Note: You can test loading the common UI URL in an iFrame on the test page


Step 5. User follows the bank feeds UI

Enter reauthentication requirements

Depending on the bank there can be various reauthorisation steps. The most common is re-entering banking credentials, other options could be to choose continue to extend their authorisation consent.

Image showing a screen for user to enter their login credentials.

Step 6. Handle messages returned from the iFrame

The Banking UI loading in the iFrame will post a message to the parent window by calling the postMessage() method. To retrieve these 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 will notify the user when the account has been reauthenticated.

 { "message": "continue", "data": { "fields": [], "acccountId": "bankAccountId", "accountStatus": "bankAccountStatus"}};

Step 7. Closing the common UI

When you recieve the account active message, you can close the UI and return the user to their in-product bank account.

Step 8. Save account details

Store the accountId returned in the post message response in the database.



In this walkthrough we have covered how to reauthorise an account through the Banking UI in an iFrame.

Was this helpful?