Creating a cVRP Consent

Purpose of cVRP consent

📘

The cVRP consent defines the parameters within which cVRP payments can be made.

Setting up the consent means a user does not need to authenticate individual payments with their bank, as long as each payment stays within the agreed limits.

The consent process generates a Consent ID which is then used to initiate subsequent cVRP payments.

Consent must be in place before any cVRP payment can be made.

Consent parameters

There are 5 core parameters contained in the consent, plus additional fields that are mandatory for cVRP:

1. Time period -- period during which the maximum amount per period is applied. Must be 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. Mandatory.
3. Maximum amount per payment -- limit on the value of any individual payment. Mandatory.
4. Period start date -- date the consent starts from. Optional; if left blank, the value provided by the bank is used.
5. Expiry date -- date the consent ends. Optional; if left blank, the value provided by the bank is used.

The following fields are additionally mandatory for cVRP:

• Type -- must be CVRP1 for Wave 1 use cases.
• Interaction types -- whether payments will be made while the user is actively present (IN_SESSION) or in the background without user interaction (OFF_SESSION). At least one must be provided. We recommend providing both IN_SESSION and OFF_SESSION if you will be supporting both payment modes, which will allow you to pass either one in the cVRP payment itself.
• Risk -- a block of fields describing the payment context. Most fields are mandatory for cVRP; see the field definitions table below for detail.
• Ultimate Creditor / Ultimate Debtor -- mandatory to capture the ultimate beneficiary or payer where they differ from the named account holder.

Creating a cVRP consent

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

Step 1: List the banks that support cVRP

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

Use the GET ASPSPs API to fetch the latest list of banks and their supported capabilities. Only institutions that have COMMERCIAL_VRP status ENABLED should be offered to the user.

This list may change over time as banks are added or their capabilities updated, so your application must handle changes dynamically.

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

Step 2: Create a cVRP consent

Request

This request creates a cVRP consent for authorisation by the user. Once authorised, the consent can be used to initiate one or more payments within its parameters.

{
  "type": "CVRP1",
  "aspspId": "H100000001",
  "destination": {
    "type": "SCAN",
    "accountNumber": "12345678",
    "sortCode": "000000",
    "name": "Example Merchant Ltd"
  },
  "paymentConstraints": {
    "maximumIndividualAmount": {
      "currency": "GBP",
      "amount": 250
    },
    "periodicLimits": [
      {
        "currency": "GBP",
        "amount": 1000,
        "periodAlignment": "CALENDAR",
        "periodType": "MONTH"
      }
    ]
  },
  "interactionTypes": [
    "IN_SESSION",
    "OFF_SESSION"
  ],
  "risk": {
    "paymentContextCode": "BillingGoodsAndServicesInAdvance",
    "merchantCategoryCode": "4900",
    "merchantCustomerIdentification": "CUST-001",
    "contractPresentIndicator": true,
    "beneficiaryPrepopulatedIndicator": true,
    "paymentPurposeCode": "BKDF",
    "categoryPurposeCode": "BONU"
  },
  "validFromDate": "2025-01-01T00:00:00Z",
  "validToDate": "2026-01-01T00:00:00Z",
  "reference": "Invoice ABC123"
}

Response - created

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

Response - bad request

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

Consent parameter definitions

📘

M = Mandatory | O = Optional | C = Conditional

• For Payment Purpose Code and Category Purpose Code, refer to the list here for the most appropriate one for your consent: OB ISO External Codeset
  • For Payment Purpose Code - use ExternalPurpose1Code from link above
  • For Category Purpose Code - use ExternalCategoryPurpose1Code from link above

Regarding paymentConstraints.periodicLimits.periodAlignment, the definitions for CONSENT and CALENDAR are as follows:

Retrieve a cVRP consent (optional)

Use the Consent ID to retrieve the full details of a cVRP consent. The response includes all fields submitted at creation, plus the current consent status. Only the customer or partner that created the consent can retrieve it.

{
  "type": "CVRP1",
  "aspspId": "H100000001",
  "destination": {
    "type": "SCAN",
    "accountNumber": "12345678",
    "sortCode": "000000",
    "name": "Example Merchant Ltd"
  },
  "paymentConstraints": {
    "maximumIndividualAmount": {
      "currency": "GBP",
      "amount": 250
    },
    "periodicLimits": [
      {
        "currency": "GBP",
        "amount": 1000,
        "periodAlignment": "CALENDAR",
        "periodType": "MONTH"
      }
    ]
  },
  "interactionTypes": ["OffSession"],
  "risk": {
    "paymentContextCode": "BillingGoodsAndServicesInAdvance",
    "merchantCategoryCode": "4900",
    "merchantCustomerIdentification": "CUST-001",
    "contractPresentIndicator": true,
    "beneficiaryPrepopulatedIndicator": true,
    "paymentPurposeCode": "BKDF",
    "categoryPurposeCode": "BONU"
  },
  "validFromDate": "2025-01-01T00:00:00Z",
  "validToDate": "2026-01-01T00:00:00Z",
  "reference": "Invoice ABC123",
  "status": "AUTHORISED"
}

Consent status model

Revoke a cVRP consent

Use the Consent ID to revoke a cVRP consent. This immediately prevents any further payments being initiated under that consent. The consent details remain retrievable after revocation.

DELETE https://api.modulrfinance.com/vrp-consents/I000000001

202 Accepted

🚧

Warning

Revoked consents cannot be reinstated. If the user wishes to continue making payments, a new consent must be created and authorised.