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

Payments Consents Flow

We offer an alternative way of enacting payments on Moneyhub which will require fewer calls to our API. This high level steps for this flow are as follows:

🚧

Prerequisites

  • You will need an API client that has the following scopes enabled:
    • auth_requests:write
    • auth_requests:read
    • payment
    • payment:read
    • payee:create
    • payee:read
  • Additionally, your client must be set up for payments as laid out here
  • Create an authorisation request for a payment
  • Navigate your user to https://identity.moneyhub.co.uk/consents/<auth-request-id> (the auth-request-id will be the ID you get when creating the above payment auth request).
  • When the user gives consent to the bank to complete the payment, the payment will be automatically submitted for you.
  • The user will redirected back to your API client redirect URI with query parameters:
    • paymentId: the ID of the submitted payment (synonymous with the mh:payment claim in the ID tokens of a normal payment)
    • authRequestId: the ID of the authorisation request created in the first step.

Create Authorisation Request

To start this flow, you need to create a payment authorisation request. The link in the high level steps will show you how to create one of those.

When specifying the bankId in the authorisation request, you can now specify a generic bank ID, like api for example. In these cases, we will show the bank chooser to the user first, and when they select their chosen bank, we will generate the bank authorisation URL and show the user the consent screen to take them to the bank.

When you create the authorisation request, you will get a response with an ID of the authorisation request. You'll use that to redirect your user to the URL https://identity.moneyhub.co.uk/consents/<auth-request-id>. From there the rest of the payment journey is handled by Moneyhub, and the banking provider the user wishes to use.

Redirect to Client

When the payment flow by the user has been complete, the user will be redirected back to the redirect URL specified in the authorisation request. If a payment was successfully submitted, you will get the query parameters laid out in the high level steps: paymentId and authRequestId. (NB: a payment may still fail even if it was successfully submitted, this could be due to fraud checks made by the bank)

These query parameter values can then be used to retrieve the payment and auth request from your client to see the payment status.

If the user cancels the consent flow, you will be redirected back to the client with an error query parameter of access_denied