---
updatedAt: 2025-08-27T16:16:22.000Z
agentTools:
  projectIndex: https://docs.moneyhubenterprise.com/v2.5/llms.txt
---

# 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.

```json
{
    "payeeId": "id-of-the-payee",
    "payee": { // payeeId or payee required
      "accountNumber": "12345678",
      "sortCode": "123456",
      "name": "payee name"
    }
    "payeeType": "api-payee", // [api-payee|mh-user-account]
    "payerId": "id-of-the-payer", // optional
    "payerType": "mh-user-account", // [api-payee|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
}
```

> Example payments claim

```json
{
    "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": "jonnsmith@email.com",
                "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.

## Payee and Payer ID

When setting the payer or payee ID, we allow for two types of IDs. These types are `api-payee` and `mh-user-acount`.

If you set an `api-payee` type, then the ID will be that of a payee type, information can be found [here](https://docs.moneyhubenterprise.com/docs/payee-management)

If it's an `mh-user-account` then the account will be from a connected bank account. The ID is 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

```json
{
    "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": "jonnsmith@email.com",
                "context": "PartyToParty"
            }
        },
        "sub": {
            "value": "61967572632b9fc48f1e0c9f" // your user ID here
        }
    }
}
```