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

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)

Scopes

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

Claims

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]",
      periodType:
        "The period over which the limit is effective [Day, Week, Fortnight, Month, Half-year, Year]",
      periodAlignment:
        "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": {
		...claims
  }
}

Authorisation

To create a recurring payment you can generate an authorization URL using the Moneyhub API Client https://github.com/moneyhub/moneyhub-api-client#getrecurringpaymentauthorizeurl

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
https://github.com/moneyhub/moneyhub-api-client#exchangecodefortokens

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

https://identity.moneyhub.co.uk/docs/#/payments/get_recurring_payments__recurringPaymentId_

StatusDescription
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
RevokedThe recurring payment consent has been revoked by the bank, user or via the API
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

https://identity.moneyhub.co.uk/docs/#/payments/post_recurring_payments**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

https://identity.moneyhub.co.uk/docs/#/payments/delete_recurring_payments__recurringPaymentId_

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
BarclaysLive
First DirectLive
HSBCLive
LloydsLiveIn development
MonzoLiveIn development
NationwideLiveIn development
Northern Bank / Danske BankLive
RBS / NatwestLiveLive
SantanderLiveIn development