Statements

To access statements information, additional ReadStatementsBasic or ReadStatementsDetail Open Banking permissions must be requested when creating a new connection or re-authenticating an existing connection. User consent must be given and the connection synced before statements will be accessible. Statements can be retrieved with basic details or with extra detail information including amounts.

🚧

Prerequisites

• An API Client with statements_basic:read or statements_detail:read scope enabled - if you haven't got this scope enabled, ask us and we can enable it for you
• An account with a banking provider that supports statements (you can use the Moneyhub Open Banking Mock if you don't have an existing real account for a banking provider with this enabled

Synchronising Statements

When you wish to synchronise statements when connecting to a bank, you will need to make a slight change when making the auth request URL. You will need to add some additional claims, and they are in this format:

{ 
	"id_token": {
		"mh:consent": {
			"essential": true,
			"value": {
				"permissions": ["ReadStatementsDetail"]
			}
		}
	}
}

If you are using the @mft/moneyhub-api-client NodeJS library we have provided, you can just add the object object to the claims key in the following call:

const data = await moneyhub.getAuthorizeUrlForCreatedUser({
  userId,
  state,
  bankId,
  nonce,
  claims,
})

On code exchange, statements should have been synced from the connecting bank connection.

Fetching Statements

When fetching the statements from the API, you will need to request an access token with either of the following scopes:

• statements_basic:read
• statements_detail:read

The only difference between the detail and non-detail is scope is that the detail scope will return the statement amounts

The scopes are scoped to a user.

We expose the following endpoint through our API:

GET /accounts/{accountId}/statements

This will retrieve all statements for an account.

Walkthrough Using NodeJS Library Example

🚧

Prerequisites

• @mft/moneyhub-api-client version 6.1.0

First ensure the example config is set to an API client you own. You'll first need to register a user if you haven't got one already:

node examples/user/register-user.js

Take note of the returned user ID, this will be used for later calls.

Next you'll need to make a call to get an authorisation URL for this user to make a banking connection. The API client has a script that allows to make this request for a URL to include the above ReadStatementsDetail permission in the request. The call to make is shown below:

node examples/auth/get-authorization-url-for-user.js -u <your-user-id> -b <bank-id>

The bank-id in the script call above is one you will find in the list from the following link: https://identity.moneyhub.co.uk/oidc/.well-known/api-connections.

📘

Statements support

Please note that not every bank supports statements at this time

Navigate to the returned URL and complete the consent for the connection. On successful consent of the banking connection, exchange the authorisation code for access tokens using the following script:

node examples/token/exchange-code-for-token.js -c <code>

Once that is complete, you can fetch the statements using the following script

node examples/accounts/get-account-statements-with-detail.js -u <user-id>

Using the Moneyhub API Client in your app

You can make use of the Moneyhub API Client to simplify the process of making a new connection with the ReadStatementsBasic or ReadStatementsDetail permissions.

You can then use the following methods to retrieve the statements for an account

getAccountStatements

getAccountStatementsWithDetail