VRP Payment - ControlParameters - Periodic limits validation

jsanhc commented 2 years ago

Description

The ASPSP must ensure that the payment instruction adheres to the limitations set by the corresponding VRP consent's ControlParameters.
When a payment would breach a limitation set by one or more ControlParameters, the ASPSP must return an error with code UK.OBIE.Rules.FailsControlParameters and pass in the control parameter field that caused the error in the Field field of the error message.

It means that the bank service simulation must be implemented a logic to store the payments to calculate the limits defined in the consent in the object ControlParameters.

Current Sandbox behaviour

Currently the Sandbox doesn't implement a real bank behaviour logic to manage the different actions done over accounts and payments, only implements the machine status pattern to change some consent status and payments status.

BohoCode commented 2 years ago

Allow TPPs to test periodic sums for VRPs.

We have implemented the 3.1.8 version of the OB APIs so we can support you when you need that version, and in particular VRP payments. We can deploy this in our Q1 release next year. However, I have some questions for you.

It was stipulated in the contract that simulation is turned off, i.e. that the payments etc are not processed and payment simulation is not done. This provides TPPs with the assurance that data returned will always be the same and makes testing easy for them.

This does raise some challenges with VRP payments though, as we need to come up with a suitable way of allowing TPPs to test the periodic control parameters. For example it is possible to set a maximum limit for payments during a specific period, e.g. £2000 per month. Then VRPs will be allowed until such time as a VRP would mean that the total VRP payments exceed £2000 in a particular month.

Bearing in mind that we don't process the VRP payments and simulate the payments, all of the transaction data in the account data you provide us, will fall outside of the control periods specified by the VRP consent. In order to allow TPPs to test this we have the following options;

a) Not test the periodic control parameters. It may be enough for TPPs to be able to create a consent and make a VRP payment.

b) Total up the value of the VRP payment submissions during the period specified in the VRP Consent Control Parameters and use that as a total and fail VRP payment submissions that would breach the control parameters.

c) Look in the headers of each VRP payment submission request and determine behaviour based on that header value. This woudl need to be documented on your developer portal. So for example we might have a header like x-vrp-payment-submission-response and we could define values that would control what responses a TPP would get from a VRP payment submission.

Of all of these options I least like b) as from a TPPs perspective behaviour of the VRP payment submission endpoint would change based on the number of VRP payments made during the control period. This would make it very hard for them to run any automated tests against the sandbox.

For these reasons, a or c are the best options we think.

jsanhc commented 2 years ago

We start to implement the solution C.

jsanhc commented 2 years ago

Spec References

VRP Control parameters 3.1.9

OBDomesticVRPControlParameters

Focus on ControlParameters.PeriodicLimits

Name	Path	Definition	Type
PeriodicLimits (0..*)	`ControlParameters.PeriodicLimits`	Maximum amount that can be specified in all payment instructions in a given period under this VRP consent. If the PeriodAlignment is Calendar, the limit is pro-rated in the first period to the remaining number of days	N/A
PeriodType (1..1)	`ControlParameters.PeriodicLimits.PeriodType`	Period type for this period limit	Day, Week, Fortnight, Month, Half-year, Year
PeriodAlignment (1..1)	`ControlParameters.PeriodicLimits.PeriodAlignment`	Specifies whether the period starts on the date of consent creation or lines up with a calendar. As the ISO calendar does not support or provide any guidance on when a fortnight should start, hence for a PeriodType of Fortnight the PeriodAlignment must be Consent.	Consent, Calendar
Amount (1..1)	`ControlParameters.PeriodicLimits.Amount`	A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.	N/A
Currency (1..1)	`ControlParameters.PeriodicLimits.Currency`	A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".	ActiveOrHistoricCurrencyCode

Examples

// created on 06-Jun-2021
{
  "PeriodType": "Month",
  "PeriodAlignment": "Calendar",
  "Amount": "300.00",
  "Currency": "GBP"
}

Period	Start	End	Applicable Limit
1	06-Jun-2021	30-Jun-2021	250.00 GBP
2	01-Jul-2021	31-Jul-2021	300.00 GBP
3	01-Aug-2021	31-Aug-2021	300.00 GBP

// created on 05-Jun-2021
{
  "PeriodType": "Month",
  "PeriodAlignment": "Consent",
  "Amount": "500.00",
  "Currency": "GBP"
}

Period	Start	End	Applicable Limit
1	05-Jun-2021	04-Jul-2021	500.00 GBP
2	05-Jul-2021	04-Jul-2021	500.00 GBP
3	05-Aug-2021	04-Sep-2021	500.00 GBP

// created on 05-Jun-2021
{
  "PeriodType": "Year",
  "PeriodAlignment": "Calendar",
  "Amount": "500.00",
  "Currency": "GBP"
}

Period	Start	End	Applicable Limit
1	06-Jun-2021	31-Dec-2021	286.30 GBP (500 x 209 / 365)
2	01-Jan-2022	31-Dec-2022	500.00 GBP
3	01-Jan-2023	31-Dec-2023	500.00 GBP

// created on 05-Jun-2021
{
  "PeriodType": "Year",
  "PeriodAlignment": "Consent",
  "Amount": "500.00",
  "Currency": "GBP"
}

Period	Start	End	Applicable Limit
1	05-Jun-2021	04-Jun-2022	500.00 GBP
2	05-Jun-2022	04-Jun-2023	500.00 GBP
3	05-Jun-2023	04-Jun-2024	500.00 GBP

`Payment limitation breach` simulation Solution

To implement a solution to simulate a Payment limitation breach we design the below solution:

The TPP can add the header x-vrp-limit-breach-response-simulation with a value from the table header values definitions.
Header value pattern: ControlParameters.PeriodicLimits.PeriodType-ControlParameters.PeriodicLimits.PeriodAlignment
The header x-vrp-limit-breach-response-simulation value pattern needs to match with the PeriodType and PeriodAlignment values set in the consent request ControlParameters.PeriodicLimits.

Look in the headers of each VRP payment submission request and determine behaviour based on that header value. This would need to be documented on customer developer portal.

PeriodType: Day, Week, Fortnight, Month, Half-year, Year
PeriodAlignment: Consent, Calendar

For example we might have a header x-vrp-limit-breach-response-simulation with the value Day-Consent that would control what responses a TPP would get from a VRP payment submission following the Header values definitions table.

Header values definitions Valid header values:	Header value	Error code	https status	Description
Valid value which matches a Periodic Limit on the Consent	`UK.OBIE.Rules.FailsControlParameters`	400	Unable to complete payment due to payment limit breach, periodic limit of '$limitAmount' '$limitCurrency' for period '$limitPeriodType' '$limitPeriodAlignment' has been breached

Exceptional Responses The below responses occur if the simulation header is set to an invalid value	Header value	Error code	https status	Description
Value is valid but does not match a Periodic Limit on the Consent	`OBRI.Request.Data.vrp.limit.breach.simulation.no.matching.limit.in.consent`	400	No Periodic Limit found in the consent for Header value '%HEADER_VALUE', unable to simulate the payment limitation breach
Invalid Value	`OBRI.Request.Data.vrp.limit.breach.simulation.invalid.header.value`	400	Invalid Header value '$HEADER_VALUE', unable to simulate the payment limitation breach ±

Exception cases

When the header x-vrp-limit-breach-response-simulation sent in the request is empty, then an error will be raised
Only the header x-vrp-limit-breach-response-simulation will be supported for limitation breach simulation.

dbadham-fr commented 2 years ago

Documentation for this functionality has been added to the wiki: VRP Payments - Periodic Limit Breach simulator for TPP testing

OpenBankingToolkit / openbanking-toolkit