API Businesses, Software & Certificates

In order for your company to act as a TPP (Third Party Provider) on the Moneyhub API platform you'll need to be setup with a Business entity in the Moneyhub Admin Portal.

Once this has been created for you it will appear under the API Businesses section and you will be able to upload Keys and Certificates and manage your registrations with each bank.

Here is a brief taxonomy to help you understand this area of our platform:

Name	Description
Business	This entity represents your business, under it you can have Software, API Clients and Certificates
Software	This is a grouping of Certificates and Credentials. The main reason to have this logic grouping is to allow you to have one software for access to mock banks, one software for access to banks that support OB certificates, and another software for access to banks that require eIDAS certificates
Certificate	This entity represents a certificate with associated private key. We support different types of "certificate", for example eIDAS QWAC or OB Transport. Some types require just a private key and a public key, whereas some require a private key and a certificate.
Credential	The contains the credentials used to connect with a provider. For most providers it is simply a client_id - although for some providers a client_secret is also required.
Provider	This is one of the financial institutions that we support connecting to, e.g barclays.
API Client	This is an OpenID Connect client that you use to authenticate with our API and gain access to resources.

Certificates

The Certificates section will allow you to upload any Open Banking certificates you have.

To upload a certificate, from the Certificates list page under your Business, click the blue button in the bottom right and select Add. For each certificate, fill out the Name and select the Usage and Type of certificate that you are adding

Public Key

These need to be provided in PEM format. This part does not need to be encrypted. If you need to convert between JWK and PEM there are tools such as Jose capable of doing this.

Private Key

This part should be kept secret and secure, and thus should be uploaded as a base64 encoded JWE. The JWE can be created from a PEM with the utility:

https://github.com/moneyhub/moneyhub-api-client/blob/master/examples/jwks/encrypt.js

This utility uses the standard JWE encryption standard and encrypts your key with our public encryption key located here: https://identity.moneyhub.co.uk/oidc/certs

📘
Public keys are rotated annually

We suggest that you review our encryption code - its simple and uses open standards.

To set this up:

git clone [https://github.com/moneyhub/moneyhub-api-client.git](https://github.com/moneyhub/moneyhub-api-client.git)
cd moneyhub-api-client
npm install
cd examples

Then finally to actually run the conversion:

node jwks/encrypt.js the-path-to-your-private-key

This should give you some output - take the content in-between but not including the dashes, e.g. from "ey" to "Fg":

--------
**eyJlbm...
...-qRFg**
--------

If you are viewing or editing this field, the value will be hidden, but will not be overwritten unless a new value is provided.

Metadata

This field allows advanced configuration to be provided and should be left blank unless necessary

Adding a Transport Certificate

When adding a Transport Certificate you will need to add the Certificate in PEM format, and the Signing Key JWE encoded as above

Adding a Signing Certificate

When adding a Signing Certificate you will need the Signing Private Key JWE encoded as above, and the KID as the External Key Id

Software and Credentials

A software is a container for your credentials and certificate types used to access a particular type of bank. You might only require a software for Open Banking standard connections, but some banks will require other types of certificates (e.g. eIDAS) and configuration, so there is an option of separating them

Setting up a Software

Create a new Software by going to the Software list page under your Business, clicking the button in the bottom right and select Add

External Software Id

This will be your Open Banking Software Statement Id (also called Client Id in the Open Banking Directory), which is used when registering with a bank, and we will also send with every request as part of the User Agent String

User Agent Name

This is a shorten version of your business name that will be added to your External Software Id and sent as part of the User Agent String with every request

External Organisation Id

This will be your Open Banking Organisation Id to be used when registering with banks

Metadata

This field allows advanced custom configuration settings to be specified, and should be left blank for now

Add Credentials

Once you have registered with a bank (banking service provider) you should receive a Client ID and Client Secret which are used to authenticate connections. Credentials for a bank should only be added to one Software and should be paired with the correct types of certificate

To add the credentials go to the detail page of the software, click the blue button in the bottom right of the page and select Add Provider Credentials

Provider

You will only see banking service providers that are currently available for connection. If you cannot see a provider in the list it may mean that you have already provided credentials under another Software within your Business entity

Usage

Credentials can be provided separately for Account Information or Payment Initiation requests. If you are in doubt select Accounts

Assign Certificates

For Open Banking you need to have uploaded an Open Banking Transport and Signing certificate. These can be linked to the software by selecting them from the Certificates & Keys list

Be careful when assigning certificates. They must be valid for all of the banks that you have provided credentials for under this Software. Your Open Banking certificates should be assigned to a different Software than your eIDAS certificates for example.

Configure your API Clients

You should now be ready to make use of your credentials. To do that we need to assign this Business to one more API Clients that you are using to the connect to the Moneyhub platform. Contact us and we can do this for you. Once done you should see the Clients that have been linked on the Business detail page