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"
    }
    "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

{
    "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.

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

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

{
    "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
        }
    }
}