Beneficiaries

A beneficiary is a payment or transfer destination account which has been authorized by the bank. Each beneficiary belongs to an account, which means that the given account can send money to that beneficiary. However, different banks treat beneficiaries in different ways. Some treat them as fully trusted, meaning no signing at all is required when transferring money to the beneficiary. Other banks treat them more as address books of registered recipients.

This section outlines how to synchronise beneficiaries from a banking connection, and then later retrieve them from our API.

🚧

Prerequisites

• An API Client with beneficiaries:read or beneficiaries_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 has beneficiaries sync enabled (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 Beneficiaries

When you wish to synchronise beneficiaries 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": ["ReadBeneficiariesDetail"]
			}
		}
	}
}

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, beneficiaries should have been synced from the connecting bank connection.

Fetching Beneficiaries

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

• beneficiaries:read
• beneficiaries_detail:read

The only difference between the detail and non-detail is scope is that the detail scope will return the beneficiary's postal address.

The scopes are scoped to a user.

There are two methods that are exposed on our API:

GET /beneficiaries

This will retrieve all beneficiaries that are linked to a user, currently we have the following filters on this end point:

• offset - pagination offset
• limit - pagination limit

GET /beneficiaries/{beneficiaryId}

This will retrieve one beneficiary with the corresponding ID. If a beneficiary with that ID doesn't exist, a 404 error will be returned, and if the beneficiary found doesn't match the user's

Walkthrough Using NodeJS Library Example

🚧

Prerequisites

• @mft/moneyhub-api-client version 4.5.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 ReadBeneficiariesDetail permission in the request. The call to make is shown below:

node examples/beneficiaries/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.

📘

Beneficiaries support

Please note that currently we are only offering this fetch beneficiaries capability on Open Banking type connections

The test banking connection OZone can be used as well to test this capability.

Monzo doesn't have the retrieval of beneficiaries on their API specification, so can't be synchronised 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 beneficiaries using the following script

node examples/beneficiaries/get-beneficiaries.js -u <user-id>

Uniqueness

When retrieving beneficiaries, a duplicate account identifier could be returned, but with a differing reference. We allow you to return just the unique beneficiaries by using the isUnique query parameter on the get beneficiaries method.

The equality of an account identifier is determined by the following properties all being identical:

• sort code
• account number
• iban
• pan

If you're using the Moneyhub client library, this call can be made as below:

const result = await moneyhub.getBeneficiaries({
  params: {
    isUnique: true,
  },
  userId: <userId>,
})