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

Payments Authorization

Creating a payment authorization url using our api client
https://github.com/moneyhub/moneyhub-api-client#getpaymentauthorizeurl

const url = await moneyhub.getPaymentAuthorizeUrl({
    bankId: "Bank id to authorise payment from",
		payeeId: "Id of payee",
  	payee: payeeObject, // payeeId or payee required
		payeeType: "Payee type [api-payee|mh-user-account]", // optional - defaults to api-payee
		payerId: "Id of payer", // optional
		payerType: "Payer type [mh-user-account]", // required only if payerId is used
		amount: "Amount in pence to authorize payment",
		payerRef: "Payer reference", // Max 18 alphanumeric characters
		state: "your state value",
		nonce: "your nonce value", // optional
		claims: claimsObject, // optional
})

To authorise a payment the user needs to be redirected to the authorization url that contains the payments claim as explained above. The generation of the authorization url can be done with our moneyhub api client as shown in this section.

Exchanging an authorization code for a token set using our api client

const tokens = await moneyhub.exchangeCodeForTokens({
    localParams: {
        nonce: "your nonce value",
        state: "your state value",
    },
    paramsFromCallback: {
        code: "code param from callback",
        state: "state from callback",
        id_token: "id_token from callback",
    },
})

Once the user has successfully granted Moneyhub consent to initiate the payment and authenticated at the bank we will return an authorization code to your redirect_uri. This must be exchanged for an access token as per standard OpenID Connect practice. If you don’t exchange the auth code for an access token, the payment will never be completed even though the user has authenticated it.

Decoded content of id token after exchanging authorization code

{
    "sub": "5cda695b82d18512e415e648",
    "mh:con_id": "1fd7ca2c94a914819b2e1b6cf0abe874:b6592e9e-619f-4171-a933-6023c381bd03",
    "mh:payment": "aeb2bc6c-505e-41b7-a82a-e898a7e95438",
    "at_hash": "3MmQIA6EtEnfo319s-UZdw",
    "sid": "8be9087f-3b9f-426e-af52-2671f2ab88aa",
    "aud": "c40d7f7a-a698-4bf1-84bf-8f3798c018b2",
    "exp": 1557821587,
    "iat": 1557817987,
    "iss": "https://identity.moneyhub.co.uk/oidc"
}

As well as receiving an access token, you will receive an id token that will have a mh_payment claim. The value of this claim in the id token will be the id of the payment.

Once that you have extracted the payment id from the id token you will need to query the status of the payment on the following endpoint: GET /payment/:id

❗️

A successful exchange of an authorisation code do not implies that the payment was successful. The payment needs to be retrieved from our API to check the status.

Expiry

Payment consents are short-lived and cannot be re-authenticated by the Payment Services user.

As long as the consent is still valid by the PISP we don't prevent going ahead with a payment but the expiration varies among PISP's.

Here are some examples

PISPExpiration time
Bank of Ireland5 minutes
Barclays2 hours
HSBC5 minutes
Lloyds Group45 minutes
Natwest Group15 minutes