Self-hosting Affordability Widget

📘

This page is for specific guidance for the Affordabilty widget, for general implementation guidance, please see implementing self-hosted single journey widgets

Parameters

This is an example code snippet that can be obtained from the widget page in our admin portal:

<div id="root"></div>
<script src="https://s3.eu-west-1.amazonaws.com/widgets.moneyhub.co.uk/widgets.bundle.js"></script>
<script type="text/javascript">
    window.moneyhub.init({
        "elementId": "root",
        "type": "standard-financial-statement",
        "widgetId": "831b0bce-130e-478c-a064-d685bd8a3cfc",
        "params": {
            "externalUserId": "external-user-id",
            "email": "[email protected]",
            "name": "Sarah Green",
            "state": "random-unique-session-string"
        },
        logger: {
            // Replace with however you wish to handle these events
            info: (page, data) => console.info(page, data),
            error: (page, data) => console.error(page, data),
        }
    })
</script>

The following data items are optional but can be included in the widget to allow the reconciliation of individual affordability reports to your systems or a better journey experience.

  • name: The end-user/applicant's name.
  • email: The end-user/applicant's email.
  • externalUserId: An identifier from your system that uniquely identifies this report request/case/application/etc..
  • state: The state value that will be returned at the end of the journey for reconciliation.

Implement

The best way to ensure you can cross-reference Moneyhub affordability reports with your reference number or ID is to pass it to us in the "external user ID" parameter as part of the URL path (not the query parameters).

The way that you should set up the pages of your site that will host the widget is as follows:

  • Make the external user ID part of the URL path of your site across any site pages that will use the affordability widget (e.g. for a reference of "REF123", you might use something like: `<https://our-site.com/application-journey/REF123>)
  • When you initialise the widget (i.e. using window.moneyhub.init), ensure that your site takes the reference number from the URL path and passes it through to the widget via the params.externalUserId property.

    🗒️

    If you are using libraries such as React this might involve taking the external user ID from the URL path using React Router and passing that down to the component where the widget is initialised as a prop, and then passing it in that way.

Receiving parameters at the end of the Journey

After a user has connected accounts and has submitted the data, we will redirect to the finish url that was configured for the widget with the following data as query params:

  • userId: Moneyhub user id that was created during the affordability journey
  • reportId: A unique identifier of the affordability report that was created
  • state: State value that was passed when initialising the widget

This is an example of a redirect URL from the end of a journey when the finish URL is set aswww.moneyhub.com/finish:

https://www.moneyhub.com/finish?reportId=9edd3853-1a25-44fe-a563-abcc513904fa&userId=63d24f731e23f51590331b1e&state=state-value