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",
        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",
        payeeRef: "Payee reference", // Max 18 alphanumeric characters
        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

PISP

Expiration time

Bank of Ireland

5 minutes

Barclays

2 hours

HSBC

5 minutes

Lloyds Group

45 minutes

Natwest Group

15 minutes