Payments Claim

When generating an authorisation URL for a payment, the following object is used to give the describe the information to make the payment, this is put in the mh:payment claim.

{
    "payeeId": "id-of-the-payee",
    "payee": { // payeeId or payee required
      "accountNumber": "12345678",
      "sortCode": "123456",
      "name": "payee name"
    },
    "payer": { // requires payerType to be "api-payer"
      "accountNumber": "12345678",
      "sortCode": "123456",
      "name": "payer name"
    },
    "payeeType": "api-payee", // [api-payee|mh-user-account]
    "payerId": "id-of-the-payer", // optional
    "payerType": "mh-user-account", // [api-payer|mh-user-account] optional
    "amount": 150, // in pence
    "payerRef": "Payer reference", // Max 18 alphanumeric characters   	
    "context": "PartyToParty", // ["Other", "BillPayment", "PartyToParty"] // optional
    "payerName": "Payer name", // Max 254 characters - optional
    "payerEmail": "Payer email",// Max 254 characters - optional
    "endToEndId": "end-to-end-id" // optional
}

Example payments claim

{
    "id_token": {
        "mh:con_id": {
            "essential": true
        },
        "mh:payment": {
            "essential": true,
            "value": {
                "payeeId": "3305bc2c-8848-4fe0-a529-a7f7d35a5722",
                "payeeType": "api-payee",
                "amount": 150,
                "payerRef": "reference to display on payer's statement",
                "payerName": "John Smith",
                "payerEmail": "[email protected]",
                "context": "PartyToParty"
            }
        }
    }
}

In order to initiate a payment via the API you need to use the payment scope and use the mh:payment claim. This claim require as a minimum the values of the payeeeId, amount, payee refrence and payer reference.

This claim must be supplied using the claims parameter semantics from OpenID Connect Core. It should be nested under the id_token key and not the userinfo key.

Using the claims parameter may feel slightly convoluted, but it is a neat standards compliant way of us allowing OAuth clients to pass us arbitrary payment values.

By putting the payment payload inside a signed request object there is non-reputable proof that the payment request was signed by your private key.

Payees

When setting the payee we allow for two types of payees. These types are api-payee, and mh-user-acount.

If you set an api-payee type, then the payeeId will need to either originate from creating a payee utilising Moneyhub's payees API, or by using a valid payee object in the claim. More information on payee management can be found here

If it's an mh-user-account then the account will be from a connected bank account. The payeeId must be in the format <user-id>:<account-id> where the user ID is the ID of the Moneyhub user the bank account belongs to, and the account ID is the ID of the connected account that belongs to the user.

Payers

Defining a payer in the payments claim can help to enhance the UX of a user's journey when navigating to their banking app. If these details are known before the payment claim is made, this can remove the additional step of selecting an account to pay from in the banking app's consent screens, resulting in a smoother user journey.

When setting the payer we allow for two types of payers. These types are api-payer and mh-user-acount.

To pass account details as an object in the claim, use the api-payer type along with a valid payer object.

Similar to payees, if it's an mh-user-account then the account will be from a connected bank account. The payerId must be in the format <user-id>:<account-id> where the user ID is the ID of the Moneyhub user the bank account belongs to, and the account ID is the ID of the connected account that belongs to the user.

Attaching User to Payment

Normally, when a payment is created, a new user is generated for that payment and attached to said payment.

If you want to create a payment that belongs to a certain user, you need to add a sub claim to the above claims. The user ID you attach must belong to the client being used to generate the authorisation URL.

Using the example above of the claims you'd send to create the request object, this can be extended as follows to attach the User ID

{
    "id_token": {
        "mh:con_id": {
            "essential": true
        },
        "mh:payment": {
            "essential": true,
            "value": {
                "payeeId": "3305bc2c-8848-4fe0-a529-a7f7d35a5722",
                "payeeType": "api-payee",
                "amount": 150,
                "payerRef": "reference to display on payer's statement",
                "payerName": "John Smith",
                "payerEmail": "[email protected]",
                "context": "PartyToParty"
            }
        },
        "sub": {
            "value": "61967572632b9fc48f1e0c9f" // your user ID here
        }
    }
}