Recurring Payments (VRP)

Creating Variable Recurring Payments through the payments API

VRPs enable customers to grant a long-lived consent to a Payment Initiation Service Provider (PISP) for the purpose of instructing a series of payments on their behalf, without the need for the PSU to authenticate each individual payment with the Account Servicing Payment Service Provider (ASPSP)


Creating recurring payments requires the recurring_payment:create scope and reading them requires the recurring_payment:read scope to be enabled on the API client


These are the values that can be passed into the moneyhub. getRecurringPaymentAuthorizeUrl method or the mh:recurring_payment claim within the id_token

  bankId: "Bank id to authorise payment from",
  payeeId: "Id of payee", // required or payee
  payeeType: "Payee type [api-payee|mh-user-account]", // defaults to api-payee
  payerId: "Id of payer", // required only if payerType is defined
  payerType: "Payer type [mh-user-account]", // required only if payerId is used
  reference: "The reference for recurring payment",
  validFromDate: "The date from which the authorisation is effective", // should be in an international format, e.g. 15-MAR-2021 or ISO date
  validToDate: "The date to which the authorisation is effective", // optional - should be in an international format, e.g. 15-MAR-2021 or ISO date
  maximumIndividualAmount: "The maximum single amount that will be allowed", // the valid in whole minor units (i.e. pence)
  currency: "The currency code for the maxiumum recurring payment amount [GBP]",
  periodicLimits: [
      amount: "The maximum amount for this recurring payment limit", // the valid in whole minor units (i.e. pence)
      currency: "The currency code for this recurring payment limit [GBP]",
        "The period over which the limit is effective [Day, Week, Fortnight, Month, Half-year, Year]",
        "Specifies whether the period starts on the date of consent creation or lines up with a calendar [Consent, Calendar]",
  type: [
    "Sweeping", // Specifies that the recurring payment is for the purpose of sweeping payments
    "Other", // Specifies that the recurring payment is for other payments of another purpose
  context: "Payment context [Other,BillPayment,PartyToParty]", // optional - defaults to PartyToParty
  state: "your state value",
  nonce: "your nonce value", // optional
  payeeId: "14edab6d-7aed-4ed3-b01b-9592a5d539c6", // An API Payee
  payeeType: "api-payee",
  bankId: "5233db2a04fe41dd01d3308ea92e8bd7", // Ozone bank
  reference: "VRP01",
  validFromDate: "2022-03-01T00:00:00.000Z",
  validToDate: "2022-04-01T00:00:00.000Z",
  maximumIndividualAmount: 1000, // £10
  currency: "GBP",
  periodicLimits: [
      amount: 2000,
      currency: "GBP",
      periodType: "Day",
      periodAlignment: "Consent",
  type: "Sweeping",
  context: "PartyToParty",
  state: "foo",
  nonce: "bar",


Claim Structure

This claims will need to sit within the mh:recurring_payment claim nested within a valueobject.

"mh:recurring_payment": {
	"value": {


To create a recurring payment you can generate an authorization URL using the Moneyhub API Client

The end user should be directed to a consent page, showing the details of the recurring payment where they can confirm and consent

Once the user has confirmed the details, they will be forwarded to the bank to login and authorise the recurring payment. The response this step is an authorisation code, which can be exchanged to complete the recurring payment setup

Consent status

When created, the recurring payment consent will have one of these statuses. To refresh the status of a recurring payment it can be requested from the /recurring-payments/:recurringPaymentId endpoint and checked with the updatedAt date

InProgressThe recurring payment consent is being authorised and has not yet been submitted to the bank
AwaitingAuthorisationThe recurring payment consent has been submitted to the bank and initiation is pending
RejectedThe recurring payment consent was rejected by the bank
AuthorisedThe recurring payment consent has been authorised and payments can be made against it
ExpiredThe recurring payment consent has expired (the validToDate is in the past)

Making a payment

When a consent has been created and authorised, payments can be made against it, within the limits set up in the consent. Payments are created by submitting payment claims to the /recurring-payments/:recurringPaymentId/pay endpoint along with the recurringPaymentId**recurringPaymentId**pay

  payeeId: "payee-id", // optional if specified in the consent
  payeeType: "api-payee", // [api-payee|mh-user-account] 
  amount: 150, // in pence
  payeeRef: "Payee ref",
  payerRef: "Payer ref",
  payeeId: "03d1bb92-dff1-49ed-8721-62090936bb3a",
  payeeType: "api-payee",
  amount: 1000,
  payeeRef: "PAYEE-REF",
  payerRef: "PAYER-REF",

Revoke consent

Consent can be revoked by the user via their bank, or via the API using the /recurring-payments/{recurringPaymentId} endpoint

Once a consent has been revoked, the revokedAt property on the VRP consent will display the timestamp at which it was revoked.

Bank support

Detailed below is the current status of VRP across UK banking institutions that Moneyhub currently support

Support is split into Sweeping (between your own accounts) or Non-sweeping (paying for bills or subscriptions) with only the former being mandated by the OBIE

Sweeping supportNon-sweeping support
Bank of IrelandIn development
Chase UKLive
First DirectLive
LloydsLiveIn development
MonzoLiveIn development
NationwideLiveIn development
Northern Bank / Danske BankLive
RBS / NatwestLiveLive
SantanderLiveIn development