VRP consent set up

VRP requires a one-time bank authentication and authorization that defines the parameters within which future transactions can be initiated without authentication.

VRP Consent Control Parameters

When creating a Variable Recurring Payment (VRP) consent via POST /vrp-consents, a set of control parameters are defined within the initiation object. These parameters are enforced by the ASPSP (the customer's bank) for the lifetime of the consent and constrain every payment initiated under it. Any payment request that falls outside these bounds will be rejected at the point of initiation.

Control parameters are set once, at consent creation, and — like the reference mode described in VRP Reference Handling — cannot be modified after the consent has been authorised. If your use case requires different limits, a new consent must be created.

Overview of Parameters

Validity Window

initiation.startDateTime and initiation.endDateTime define the overall active window for the consent.

• Both are provided as ISO 8601 timestamps (e.g. 2017-04-05T10:43:07.123+01:00).
• startDateTime cannot be earlier than the current time. If omitted, the time of consent creation is used as the default.
• endDateTime is optional but strongly recommended — an open-ended consent should be a deliberate choice, not a default.
• Payment initiation requests outside this window will be declined regardless of other control parameters being satisfied.

Individual Amount Limits

initiation.minimumIndividualAmount and initiation.maximumIndividualAmount bound the value of any single payment made under the VRP consent.

• Both are expressed as strings with up to four digits after the decimal point (e.g. "5.0", "10000.0"), denominated in the consent's currency.
• maximumIndividualAmount is required; minimumIndividualAmount is optional.
• minimumIndividualAmount must not exceed maximumIndividualAmount, nor any of the periodicLimits.maximumAmount values.
• These are per-payment caps, independent of periodic limits — a payment must satisfy the individual amount bounds and any applicable periodic limit to succeed.

Periodic Limits

initiation.periodicLimits is a required array defining recurring caps on cumulative payment value over a period. At least one entry must be specified, and where multiple entries are provided, they are applied together as an intersection — a payment must satisfy all of them simultaneously.

Each entry includes:

Maximum Occurrences

initiation.maximumOccurrences optionally caps the total number of payments that can be initiated under the consent. Once this number is reached, any further payment attempts will be rejected. A value of 0 is treated as "not set"; negative values are not permitted.

Example

"initiation": {
  "refId": "9htio4a1sp2akdr1aa",
  "remittanceInformationPrimary": "Sweepco",
  "scheme": "VRP_SWEEPING",
  "localInstrument": "FASTER_PAYMENTS",
  "currency": "GBP",
  "startDateTime": "2026-07-08T00:00:00.000+01:00",
  "endDateTime": "2027-07-08T00:00:00.000+01:00",
  "minimumIndividualAmount": "1.00",
  "maximumIndividualAmount": "100.00",
  "periodicLimits": [
    {
      "maximumAmount": "500.00",
      "periodType": "MONTH",
      "periodAlignment": "CALENDAR"
    },
    {
      "maximumAmount": "150.00",
      "periodType": "WEEK",
      "periodAlignment": "CONSENT"
    }
  ],
  "maximumOccurrences": 12
}

Design Considerations

• Set limits conservatively but realistically. Overly tight periodicLimits are a common cause of unexpected payment rejections downstream — model expected transaction volumes before finalising values.
• Align periodAlignment with your billing cycle. If your product bills on a calendar-month basis, CALENDAR alignment will match customer expectations more closely than CONSENT-anchored rolling periods.
• Use maximumOccurrences deliberately. It's a useful backstop for use cases with a known, finite number of expected payments (e.g. an instalment plan), but should generally be left unset for open-ended sweeping consents.
• Combine with reference mode deliberately. A dynamic reference consent with generous periodicLimits is well suited to variable, ad hoc collections; a static reference consent with tighter limits suits fixed recurring subscriptions.

Payment Reference Handling in VRP Workflows

Token's platform supports both static and dynamic references for Variable Recurring Payments (VRPs), giving you flexibility in how you structure recurring payment reconciliation.

Static Reference

If a VRP consent is created with a reference (remittanceInformationPrimary) specified at consent creation, this reference is locked for the lifetime of that consent. Every subsequent payment initiated under that VRP consent must use the same value for remittanceInformationPrimary as was set at consent creation. Payment requests attempting to use a different reference will be rejected.

Use a static reference when your reconciliation model ties a single consent to a single, fixed payment identifier — for example, a recurring subscription where the reference never needs to change.

Dynamic Reference

If a VRP consent is created without a reference (i.e. remittanceInformationPrimary is omitted at consent creation), the consent is treated as supporting a dynamic reference. In this case, each individual payment initiated under that consent can specify its own remittanceInformationPrimary value, and different payments under the same consent can use different references.

Use a dynamic reference when payments under a single VRP consent need distinct, per-payment identifiers — for example, variable one-off top-ups or ad hoc collections where each payment needs its own reconciliation reference.

Bank Support for Dynamic Reference

Support for dynamic reference is dependent on the receiving ASPSP (bank) and is not universally available across the UK open banking ecosystem. Before relying on dynamic reference for a given customer flow, confirm that the customer's bank is on the supported list below.

If a customer's bank does not support dynamic reference, a static reference must be used — the VRP consent should be created with remittanceInformationPrimary set, and all payments under that consent must use the same value.

Supports Dynamic Reference

Does Not Support Dynamic Reference

Note: This list reflects current ASPSP capability and is subject to change as banks roll out further VRP functionality. Where a bank isn't listed, treat dynamic reference support as unconfirmed and default to static reference until verified.

Summary

Note: Whether a reference is set at consent creation determines the reference mode for the lifetime of that consent — this cannot be changed after the consent has been created. Choose the appropriate mode based on your reconciliation requirements before initiating the consent.

Integration

This consent may be set up using either:

• the Hosted Pages (HP) integration - the TPP uses Token.io's HP to display the parameters of the VRP consent setup.

• the API-only integration - the TPP owns the user experience for VRP consent set up.

If you have any feedback about the developer documentation, please contact devdocs@token.io