Financial Relationship Verification

The method of verifying whether a user has a certain type of financial relationship

Prerequisites

You will need to log in to the API Gateway by retrieving an access token from the identity service. The moneyhub-api-client can be used to retrieve this, make sure the API client is configured correctly to do this. If you choose to not use the moneyhub-api-client, make sure you use the following scopes to go through this guide:

  • financial_relationship:read

Copy the access token returned and login to the API Gateway docs by putting Bearer ${accessToken} into the login modal.

❗️

Bespoke configuration

Moneyhub works with each client to create bespoke rules that the endpoint uses to verify each financial relationship.
If you wish to use this endpoint, please contact us to discuss your use case.

What is a financial relationship?

A Financial Relationship means any relationship in which a party has received, or is expected to receive, cash or something of value, directly or indirectly, from a counterparty. This exchange can be obtained either as a one-time event; or regularly or irregularly over some time.

There are many categories of financial relationships that the service can look for; these include but aren't limited to (salary, benefits, gambling organisation, mortgage, and rental tenancy).

How is a financial relationship verified?

Each category of financial relationship has different expectations, so different rules verify it. Moneyhub works with each API client to specify the financial relationship category requirements for the use case.

The initial aim in most cases is to replicate existing processes before refinement and finally sign-off. Moneyhub uses the below framework to start crafting the verification process.

  • Direction of the transactions
    • Crediting/Debiting/All transactions
  • Counterparty to the transactions align with the expectation
  • Confidence in reference used in payment aligning with expected use
  • Confidence in the transaction amount aligning with expected use
  • Age of relationship (up to 12 months at initial sync or if one-time connection)
  • Age of most recent transaction (up to 12 months at initial sync or if one-time connection)
  • Presence of regular transactions
    • Consistency/variation of transactions amounts
    • Presence of breaks in payments where payments stopped or paused

Using some, all of the above, or additional checks, the service then calculates its confidence in the existence of the financial relationship.

Expected result to be returned

When the service has calculated a report, it sends a webhook to the client.
The client can then retrieve the result from the endpoint using the id in the webhook.

The report will look slightly different use case to use case; however, it will contain the following information as a minimum:

  1. ID of the report
  2. Type of financial relationship that the service is verifying
  3. Date and time of the report
  4. Date and time of the connection
  5. Did the service verify the financial relationship as per the framework?
  6. To what confidence is the existence verifiable?
  7. A breakdown of the calculation against the framework
{
  id:"dfc8c60a-e045-4e34-a0d9-f3968aab6f3a",
  type:"Employment Benefit",
  reportDate:"",
  extractDate:"",
  result:true,
  confidence:0.95,
  report:{
    direction:{
      crediting:1.0,
      debiting:0,
    },
    age:4,
    lastest:14,
    transactionValuesWithinThreshold:1.0,
    regular:{
      detected:false,
    },
  },
}