VRP consent

Creating a consent and revoking a consent

📘

Purpose of VRP consent

The VRP consent defines the parameters within which sweeping VRP payments can be made

Setting up the VRP consent means a PSU does not have to authenticate individual payments with their bank (as they do with PIS) so long as the payment is within the parameters of the consent

The consent process generates a Consent ID which is used to make subsequent VRP payments

Providing VRP consent is the first step in the customer journey. If the PSU has not provided consent, then no VRP payments can be made

Consent parameters

There are 5 parameters contained in the consent – these are covered in detail further down this page:

1. Time period – period during which the ‘Maximum amount per period’ is applied. User must select one of Day, Week, Fortnight, Month, Half-Year, Year
2. Maximum amount per period – limit on the cumulative value of payments within the time period. User must populate this parameter
3. Maximum amount per payment – limit on the value of an individual payment that can be made. User must populate this parameter
4. Period start date – date the consent starts from. This can be left blank; see next slide for further details
5. Expiry date – date the consent ends. This can be left blank; see next slide for further details

Creating a VRP consent

The diagram below provides a high-level overview of the VRP consent creation process.

Step 1: Listing the banks that support standing order initiation

As part of the consent authentication process the user will need to select their bank so that they can be directed to the relevant authentication URL.

You should use the GET ASPSPs API to fetch the latest list of banks and their supported capabilities (such as Sweeping VRP, Single Immediate Payments and Standing Order).

Only institutions that support the capability type SWEEPING_VRP and are Enabled should be offered to the end-user.

This list may change from time-to-time, as we add new banks or change their supported capabilities, so you must ensure that your application can handle changes dynamically.

GET /aspsps

[
  {
    "type" : "SINGLE_IMMEDIATE",
    "status" : "DISABLED"
  },
  {
    "type" : "STANDING_ORDER",
    "status" : "DISABLED"
  },
  {
    "type" : "SWEEPING_VRP",
    "status" : "ENABLED"
  }
]

Step 2: Create a VRP consent

Request

This request creates a VRP consent for authorisation by the payment service user. The consent can then be used to initiate one or more payments within the parameters contained in the consent.

When creating a consent, you can set various restrictions like start and end dates, individual payment limits, and periodic limits. Periodic limits let you determine the maximum amount that can be paid through the consent during a certain time period.

POST /vrp-consents

{
  "aspspId": "H100000001",
  "destination": {
    "type": "ACCOUNT",
    "id": "A1100001",
    "accountNumber": "12345678",
    "sortCode": "000000",
    "name": "Test"
  },
  "paymentConstraints": {
    "maximumIndividualAmount": {
      "currency": "string",
      "amount": 100
    },
    "periodicLimits": [
      {
        "currency": "string",
        "amount": 100,
        "periodAlignment": "string",
        "periodType": "string"
      }
    ]
  },
  "validFromDate": "2022-01-31T20:16:01.9Z",
  "validToDate": "2022-07-31T20:16:01.9Z",
  "type": "string",
  "reference": "Invoice ABC123"
}

Response - created

POST /vrp-consents

{
  "vrpConsentInitiationId": "I000000001",
  "redirectUrl": "https://www.bankofmoney.com/authorize"
}

Response - bad request

POST /vrp-consents

  {
    "field": "string",
    "code": "GENERAL",
    "errorCode": "string",
    "message": "string",
    "sourceService": "string"
  }

Consent parameter definitions

Field	Description	Type	Request M/O/C	Validation
aspspId	Identifier of the payer’s ASPSP where the consent will be created. The ASPSP must have the “SWEEPING” capability enabled (which can be checked using our API).	String 10	M	ASPSP must have the sweeping capability enabled otherwise the request to create the consent must be rejected.
type	Type of VRP consent that will be created. Must be one of “SWEEPING” or “NON_SWEEPING”. Note that “NON_SWEEPING” is not yet available.	Enum	M	Can be one of: - SWEEPING - NON_SWEEPING. If NON_SWEEPING is submitted, request should be rejected with forbidden.
destination	Destination account details that will receive variable recurring payments initiated using this consent.	Object	M	-
destination.type	Indicates the type of destination account. Use “ACCOUNT” if the destination account is a Modulr account otherwise use “SCAN” and provide the corresponding account details.	Enum	M	Can be one of: - ACCOUNT - SCAN
destination.id	Identifier of the Modulr account when using “ACCOUNT” type.	String 8 to 10	C	Must be provided if destination.type is ACCOUNT.
destination.accountNumber	Account Number of the destination account when using “SCAN” type.	String 8	C	Must be provided if destination.type is SCAN.
destination.sortCode	Sort Code of the destination account when using “SCAN” type.	String 6	C	Must be provided if destination.type is SCAN.
destination.name	Name of the destination account when using “SCAN” type.	String 70	C	Must be provided if destination.type is SCAN.
paymentContraints	Limits that will apply to payments initiated using this consent.	Object	M	-
paymentContraints.maximum IndividualAmount	Maximum amount of any single payment initiated using this consent.	Object	M	-
paymentContraints.maximum IndividualAmount.amount	Maximum amount of any single payment initiated using this consent.	String	M	Positive amounts with a maximum of two decimal places.
paymentContraints.maximum IndividualAmount.currency	Currency of the maximum individual amount. Must be specified in ISO 4217 format.	String	M	Only allowable value is GBP. Must be specified in ISO 4217 format.
paymentContraints. periodicLimits	Maximum amount of all payments that can be initiated using this consent in a given period. If the periodAlignment is “Calendar”, the limit is pro-rated in the first period to the remaining number of days.	Object	M	-
paymentContraints. periodicLimits.amount	The maximum amount of all payments initiated using this consent in the specified period. At least one periodic limit is required.	String	M	There must be at least one periodic limit supplied.
paymentContraints. periodicLimits.currency	Currency of the maximum amount. Must be specified in ISO 4217 format.	String	M	Only allowable value is GBP.
paymentContraints. periodicLimits.periodAlignment	Specifies whether the period starts on the date of consent creation or lines up with a calendar.	Enum	M	Can be one of: - CONSENT - CALENDARValidate that only one type is used per consent.
paymentContraints. periodicLimits.periodType	Period type. Must be one of “DAY”, ”WEEK”, ”FORTNIGHT”, ”MONTH”, ”HALF_YEAR”, ”YEAR”.	Enum	M	Can be one of: - DAY - WEEK - FORTNIGHT - MONTH - HALF_YEAR - YEARValidate that there are no duplicates.
validFromDate	Start date time from which payments can be initiated using this consent. Must be specified using YYYY-MM-DDTHH:mm:ssZ format. If you do not specify a value, the consent will be created using the value provided by the bank.	ISODateTime	O	Must match YYYY-MM-DDTHH:mm:ssZ format. Must be earlier than or equal to the valid to date.
validToDate	End date time after which payments cannot be initiated using this consent. Must be specified using YYYY-MM-DDTHH:mm:ssZ format. If you do not specify a value, the consent will be created using the value provided by the bank.	ISODateTime	O	Must match YYYY-MM-DDTHH:mm:ssZ format. Must be later than or equal to the valid from date.
Reference	A reference to be used for the consent. Min 6 to max 18 characters. Can contain alphanumeric, '-', '.', '&', '/' and space.	String	O	Min 6 to max 18 characters. Can contain alphanumeric, '-', '.', '&', '/' and space.

Regarding the field paymentContraints.periodicLimits.periodAlignment the definitions for consent and calendar are as follows:

Period Alignment	Definition
consent	Maximum amount that can be paid during the defined time period (week, month, etc.) starts from the moment the user agrees the consent.
calendar	Maximum amount that can be paid during the defined time period (week, month, etc.) is based on calendar dates. Should the user give consent halfway through a period, the maximum amount is proportionately adjusted to cover the remaining duration of that time period. For example, if a user sets a maximum amount of £10,000 per month and provides consent halfway through the month, for the remainder of that month they can pay £5,000. This will then reset back to £10,000 at the start of the next month.

Retrieve a VRP consent (optional)

Use the Consent ID to retrieve information about a given Variable Recurring Payment consent. Only the customer/partner that created the consent has access to read the consent.

GET /vrp-consents/{consentId}

{
  "aspspId": "H100000001",
  "destination": {
    "type": "ACCOUNT",
    "id": "A1100001",
    "accountNumber": "12345678",
    "sortCode": "000000",
    "name": "Test"
  },
  "paymentConstraints": {
    "maximumIndividualAmount": {
      "currency": "string",
      "amount": 100
    },
    "periodicLimits": [
      {
        "currency": "string",
        "amount": 100,
        "periodAlignment": "string",
        "periodType": "string"
      }
    ]
  },
  "reference": "Invoice ABC123",
  "validFromDate": "2022-01-31T20:16:01.9Z",
  "validToDate": "2022-07-31T20:16:01.9Z",
  "type": "string",
  "status": "string"
}

Consent Status Model

Consent State	Description
AWAITING_AUTHORISATION	The consent is awaiting authorisation by the payment service user.
AUTHORISED	The consent has been successfully authorised.
REJECTED	The consent has been rejected by the payment service user.
REVOKED	The consent resource has been revoked by the payment service user.
EXPIRED	The consent has expired - only applicable if a consent expiry date was specified during consent set-up
ER_GENERAL	Generic error occurred when processing the VRP consent initiation.
ER_EXTSYS	The VRP consent initiation failed because there was a problem communicating with the bank’s systems.

Revoke a VRP consent

Use the Consent ID to cancel a VRP consent - this removes the ability to make further variable recurring payments using the consent. Information about the consent can still be retrieved and viewed by the user after the consent has been revoked.

DELETE /vrp-consents/{consentId}

🚧

Warning

It is important to note that revoked consents cannot be reinstated. The user must create a new VRP consent if they wish to set up recurring payments. See ‘Create VRP consent’ for details.

Bank Specific Limitations

Some banks have limitations in their VRP behaviour, these can be found below:

Bank	Limitation
Monzo	TheperiodicLimits.periodAlignment can be of type CONSENT only. The periodicLimits.periodtypecan only be defined as MONTHLY or YEARLY