# 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

| Parameter | Field | Description |
|  --- | --- | --- |
| Validity window (start) | `initiation.startDateTime` | The date and time from which payments can be made. Payments initiated before this time will be rejected. |
| Validity window (end) | `initiation.endDateTime` | The date and time before which payments can be made. Payments initiated after this time will be rejected. |
| Currency | `initiation.currency` | The ISO 4217 currency code for the consent. All amounts on the consent, and all payments made under it, must use this currency. |
| Minimum individual amount | `initiation.minimumIndividualAmount` | The minimum amount permitted for any single payment under the consent. |
| Maximum individual amount | `initiation.maximumIndividualAmount` | The maximum amount permitted for any single payment under the consent. |
| Periodic limits | `initiation.periodicLimits` | One or more recurring limits capping cumulative payment value within a defined period. |
| Maximum occurrences | `initiation.maximumOccurrences` | The total number of payments that can be initiated under the consent. |


## 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:

| Field | Description |
|  --- | --- |
| `maximumAmount` | The maximum cumulative transaction amount permitted within the period, up to four digits after the decimal point. |
| `periodType` | The cadence of the limit. One of `DAY`, `WEEK`, `MONTH`, `YEAR`. |
| `periodAlignment` | Whether the period is aligned to the **consent start date** (`CONSENT`) or the **calendar** (`CALENDAR`). Defaults to `CONSENT` if not specified. The consent start date is derived from `startDateTime` (time element disregarded), or the consent creation date if `startDateTime` is not set. |


## 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


```json
"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

| Bank Name |
|  --- |
| AIB UK |
| Bank of Scotland |
| Chase |
| Danske Bank UK |
| Halifax |
| Lloyds |
| Monzo |
| Santander |


#### Does Not Support Dynamic Reference

| Bank Name |
|  --- |
| Barclays |
| NatWest |
| Nationwide |
| Royal Bank of Scotland (RBS) |
| Ulster Bank NI |


> **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

| Consent Setup | Payment Behavior |
|  --- | --- |
| Reference set at consent creation | All payments must use that exact same reference |
| No reference set at consent creation | Each payment may specify its own, independent reference |


> **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)](#hosted-pages-hp-integration) integration - the TPP uses Token.io's HP to display the parameters of the VRP consent setup.


See [Hosted Pages v2](../../hosted-pages/hosted-pages-v2/hosted-pages-v2) and [Hosted Pages v1](../../hosted-pages/hosted-pages-v1/hosted-pages-v1) for more information on how to implement the Hosted Pages for VRP.

- the [API-only](#api-only-integration) integration - the TPP owns the user experience for VRP consent set up.


The user may revoke consent with the bank at any time via the TPP.

If you have any feedback about the developer documentation, please contact [devdocs@token.io](mailto:devdocs@token.io)