OpenBankingToolkit/openbanking-toolkit

VRP Payment - ControlParameters - Periodic limits validation

Opened this issue · 4 comments

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.

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.

We start to implement the solution C.

Spec References

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.

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