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
}
}
}
Updated 3 months ago