These docs are for v2.5. Click to read the latest docs for v3.0.

Benefits & Counterparties Check

Moneyhub provides two claims that allow the checking of transactions in a connection for the existence of counterparties. These claims are:

  • mh:benefits_check: this will check for the existence of benefits payments in the connection. The counterparties that are used to check for these transactions are managed by Moneyhub
  • mh:counterparties_check: the client may provide a list of counterparty IDs to check for. If one transaction has a counterparty that matches the given list, this will return a true value.

Below are examples of how to make the request object in the authorisation URL to have these claims:

{
  "id_token":{
    "sub":{
      "essential":true
    },
    "mh:con_id":{
      "essential":true
    },
    "mh:counterparties_check":{
      "essential":true,
      "value":{
        "counterparties":[
          "887468fe-da4b-4c85-ad28-73ad06adf878",
          "371e0ec3-a8a2-47da-9534-daa7404b595c"
        ]
      }
    }
  }
}
{
  "scope": "openid id:all",
	"claims": {
    "id_token": {
      "sub": {
        "essential": true
      },
      "mh:con_id": {
        "essential": true
      },
      "mh:benefits_check": {
        "essential": true,
        "value": {
          "checkTransactionsFromDate": "2021-01-01"
        }
      }
    }
  }
}

If the connection finds transactions that match either the given counterparty IDs given for the mh:counterparties_check or the configured counterparties for the mh:benefits_check claim, then the ID token will return a true result, otherwise it'll return a false.

For the mh:benefits_check, you can specify in the value a property called checkTransactionsFromDate which will be set to the date at which transactions will be checked from for the benefits transactions. This allows for more transactions to be fetched than need to be checked for benefits.

Value Properties

Below is a description of the object properties that can be sent to each claim:

  • mh:counterparties_check
    • counterparties (required) - a list of the counterparties you wish to check for (one transaction with one of this list will return a true result
    • creditOrDebit (optional) - if specified, must be either credit or debit, when specified, only transactions that are credit, or debit (depending on what is specified here) will be considered for the counterparty check
  • both mh:counterparties_check and mh:benefits_check
    • checkTransactionsFromDate (optional) - if specified, must be a valid ISO date string. When specified, it will only check for transactions from the specified date

Testing With Our Open Banking Mock

You can test this on our Open Banking mock by using a custom made log in for the bank, with the following details:

For an account that has a benefit transaction included:

  • username: benefit
  • password: benefit

For an account that doesn't have transactions for benefits:

  • username: nobenefit
  • password: nobenefit