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 avalue
object."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_
Status | Description |
---|---|
InProgress | The recurring payment consent is being authorised and has not yet been submitted to the bank |
AwaitingAuthorisation | The recurring payment consent has been submitted to the bank and initiation is pending |
Rejected | The recurring payment consent was rejected by the bank |
Authorised | The recurring payment consent has been authorised and payments can be made against it |
Revoked | The recurring payment consent has been revoked by the bank, user or via the API |
Expired | The 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 support | Non-sweeping support | |
---|---|---|
Bank of Ireland | In development | |
Barclays | Live | |
First Direct | Live | |
HSBC | Live | |
Lloyds | Live | In development |
Monzo | Live | In development |
Nationwide | Live | In development |
Northern Bank / Danske Bank | Live | |
RBS / Natwest | Live | Live |
Santander | Live | In development |
Updated 10 months ago