# Domestic VRP consents - v4.0

# Overview

The Domestic VRP Consents resource is used by a TPP to register a consent to initiate one or more of domestic payments within the control parameters agreed with the PSU.

This resource description should be read in conjunction with a compatible Variable Recurring Payments API Profile.

The PISP must call the end-point with the appropriate scope that they have been assigned. The ASPSP may use the scope to limit to functionality to sweeping or non-sweeping usage of the VRP.

# Endpoints

Resource Operation Endpoint Mandatory Scope Grant Type Message Signing Idempotency Key Request Object Response Object
domestic-vrp-consents POST POST /domestic-vrp-consents Mandatory payments Client Credentials Signed Request Signed Response Yes OBDomesticVRPConsentRequest OBDomesticVRPConsentResponse
domestic-vrp-consents GET GET /domestic-vrp-consents/{ConsentId} Mandatory payments Client Credentials Signed Response No NA OBDomesticVRPConsentResponse
domestic-vrp-consents DELETE DELETE /domestic-vrp-consents/{ConsentId} Mandatory payments Client Credentials NA No NA None
domestic-vrp-consents POST POST /domestic-vrp-consents/{ConsentId}/funds-confirmation Mandatory payments Authorization Code Signed Request Signed Response No OBVRPFundsConfirmationRequest OBVRPFundsConfirmationResponse
domestic-vrp-consents PUT PUT /domestic-vrp-consents/{ConsentId} Optional payments Client Credentials Signed Request Signed Response Yes OBDomesticVRPConsentRequest OBDomesticVRPConsentResponse
domestic-vrp-consents PATCH PATCH /domestic-vrp-consents/{ConsentId} Optional payments Client Credentials Signed Request Signed Response Yes OBDomesticVRPConsentRequest OBDomesticVRPConsentResponse

# POST /domestic-vrp-consents

The API endpoint allows the TPP to ask an ASPSP to create a new domestic-vrp-consents resource.

The request payload may contain Debtor Accounts, but the PSU may not have been identified by the ASPSP.

The endpoint allows the TPP to send a copy of the consent (between PSU and TPP) to the ASPSP for the PSU to authorise.

The ASPSP creates the resource and responds with a unique ConsentId to refer to the resource.

The default/initial Status of the resource is set to AWAU.

If the parameters specified by the TPP in this resource are not valid, or fail any rules, the ASPSP must return a 400 Bad Request. In such a situation a resource is not created.

The ASPSP must allow a PSU to have multiple VRP consents for a given account. This could include multiple consents with the same PISP.

The ASPSP must reject a consent request that has Data.ControlParameters.SupplementaryData that it cannot process.

Remittance Information MAY be provided in the Initiation section when a VRP Consent is setup. This means the same Remittance Information MUST be provided by the PISP in the Initiation and Instruction section of each VRP Payment.

An ASPSP may choose to support Dynamic references for VRP, in which case the following guidance should be used: If each VRP Payment requires dynamic Remittance Information for each VRP Payment then the Remittance Information at the VRP Consent level MUST NOT be captured. The Remittance Information in the Initiation section provided at the VRP Payment level MUST match the Initiation section provided at the VRP Consent level.

Examples:

Remittance Information Initiation section
(VRP Consent)
Initiation section
(VRP Payment)
Instruction section
(VRP Payment)
Creditor Information/Reference Credit Card No Credit Card No Credit Card No
Creditor Information/Reference Empty Empty Dynamic reference for each payment
Creditor Information/Reference Empty Empty Dynamic Invoice number for each payment

# GET /domestic-vrp-consents/{ConsentId}

A TPP can retrieve a VRP consent resource that they have created to check its status at any point of time using this API.

# DELETE /domestic-vrp-consents/{ConsentId}

A TPP can delete a VRP consent resource that they have created by calling this API.

# POST /domestic-vrp-consents/{ConsentId}/funds-confirmation

This API endpoint allows the TPP to ask an ASPSP to confirm funds on the DebtorAccount associated with the domestic-vrp-consent.

An ASPSP can only respond to a funds confirmation request if the resource has a Status of AUTH.

If resource has any other Status, the ASPSP must respond with a 400 (Bad Request) and a U009 (UK.OBIE.Resource.InvalidConsentStatus) error code.

# PUT /domestic-vrp-consents/{consentId}

This endpoint is only used for migration of consent data across API Standard versions. The ASPSP can choose to implement one or both of the PUT/PATCH endpoints and TPPs should refer to the ASPSP developer portal for information on availability.

This endpoint should not be used to modify content of an existing consent created on the same version. The ASPSP must reject request if a TPP attempts to modify an existing resource which does not require migration to the new format.

The request body should contain the correct schema for the current version of the API specification with any associated enumeration values that have moved to short code format. Values originally supplied in the consent such as account information, control parameters, dates or monetary values must not change and the ASPSP must reject any requests which modify these values.

Successful submission must return the updated consent resource body.

# PATCH /domestic-vrp-consents/{consentId}

This endpoint is only used for migration of consent data across Standard versions. The ASPSP can choose to implement one or both of the PUT/PATCH endpoints and TPPs should refer to the ASPSP developer portal for information on availability.

This endpoint should not be used to modify content of an existing consent created on the same version. The ASPSP must reject request if a TPP attempts to modify an existing resource which does not require migration to the new format.

The request body should contain an array of JSON Patch operations, as per RFC 6902 (opens new window), adressing only the changed schema and any associated enumeration values that have moved to short code format, matching the current API specification. Values originally supplied in the consent such as account information, control parameters, dates or monetary values must not change and the ASPSP must reject any requests which modify these values.

PATCH operations are atomic, all requested changes are successfully applied or none are. Errors should reflect the underlying cause and indicate which field caused the failure if relevant.

The following examples shows a series of patch operations that updates the ContractPresentIndicator field name and updates the AddressType value to the ISO code value.

[
 { "op": "remove", "path": "/Risk/ContractPresentInidicator" },
 { "op": "add", "path": "/Risk/ContractPresentIndicator", "value": "true" },
 { "op": "replace", "path": "/Data/Initiation/CreditorPostalAddress/AddressType", "value": "HOME" }
 { "op": "replace", "path": "/Risk/DeliveryAddress/AddressType", "value": "HOME" }
]

Successful submission must return the full updated consent resource body.

# State Model - VRP consents

The state model for the VRP consents resource follows the generic consent state model. However, it does not use the COND Status.

VRP Consent State model

All domestic-vrp-consents start off with a Status of AWAU

Once the PSU authorises the resource - the Status will be set to AUTH.

If the PSU rejects the consent, the Status will be set to RJCT.

The available status codes for the VRP consents resource are:

  • AWAU
  • RJCT
  • AUTH
  • CANC
  • EXPD

The definitions for the Status:

Status Description
1 AWAU The consent resource is awaiting PSU authorisation.
2 RJCT The consent resource has been rejected.
3 AUTH The consent resource has been successfully authorised.
4 CANC The consent resource has been canceled.
5 EXPD The consent resource has expired.

Changes to the Status, such as being rejected, should be captured in StatusReason, an array of StatusReasonCode, StatusReasonDescription and Path.

Field Description
StatusReasonCode Code directly relating to the reason for the current Status. See OBExternalStatusReason1Code in OB_Internal_CodeSet (opens new window) for appropriate values.
StatusReasonDescription Description of why the code was returned
Path Path is optional but relevant when the status reason refers to an object/field and hence conditional to provide JSON path.

# Data Model

The data dictionary section gives the detail on the payload content for the VRP consent API flows.

# Reused Classes

# OBProxy1

The OBProxy1 class is defined in the vrp-profile page.

# OBPostalAddress7

The OBPostalAddress7 class is defined in the vrp-profile page.

# OBRemittanceInformation2

The OBRemittanceInformation2 class is defined in the vrp-profile page.

# OBUltimateCreditor1

The OBUltimateCreditor1 class is defined in the vrp-profile page.

# OBUltimateDebtor1

The OBUltimateDebtor1 class is defined in the vrp-profile page.

# OBRegulatoryReporting1

The OBRegulatoryReporting1 class is defined in the vrp-profile page.

# OBCashAccountDebtorWithName

OBCashAccountDebtorWithName

Name Path Definition Type
SchemeName (1..1) SchemeName Name of the identification scheme, in a coded form as published in an external list. Namespaced Enumeration OBInternalAccountIdentification4Code

For more information see OB_Internal_CodeSet here (opens new window)
Identification (1..1) Identification Identification assigned by an institution to identify an account. This identification is known by the account owner. Max256Text
Name (1..1) Name Name of the account, as assigned by the account servicing institution. Usage: The account name is the name or names of the account owner(s) represented at an account level. The account name is not the product name or the nickname of the account. Max70Text
SecondaryIdentification (0..1) SecondaryIdentification This is secondary identification of the account, as assigned by the account servicing institution. This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination) Max34Text
Proxy (0..1) Proxy Specifies an alternate assumed name for the identification of the account. OBProxy1

# OBCashAccountCreditor3

OBCashAccountCreditor3

Name Path Definition Type
SchemeName (1..1) SchemeName Name of the identification scheme, in a coded form as published
Identification (1..1) Identification Identification assigned by an institution to identify an account. This identification is known by the account owner. Max256Text
Name (1..1) Name Name of the account, as assigned by the account servicing institution, in consent with the account owner in order to provide an additional means of identification of the account. Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number. OB: No name validation is expected for confirmation of payee. Max70Text
SecondaryIdentification (0..1) SecondaryIdentification This is secondary identification of the account, as assigned by the account servicing institution. This can be used by building societies to additionally identify accounts with a roll number__ (in addition to a sort code and account number combination). Max34Text
Proxy (0..1) Proxy Specifies an alternate assumed name for the identification of the account. OBProxy1

# OBBranchAndFinancialInstitutionIdentification6

OBBranchAndFinancialInstitutionIdentification6

Name Path Definition Type
SchemeName (0..1) SchemeName Name of the identification scheme, in a coded form as published in an external list. OBInternalFinancialInstitutionIdentification4Code
Identification (0..1) Identification Unique and unambiguous identification of a financial institution or a branch of a financial institution. Max35Text
Name (0..1) Name Name by which an agent is known and which is usually used to identify that agent. Max140Text
LEI (0..1) LEI Legal entity identification as an alternate identification for a party.
Legal Entity Identifier is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)".
Max20Text
PostalAddress (0..1) PostalAddress Information that locates and identifies a specific address, as defined by postal services. OBPostalAddress7

# OBDomesticVRPInitiation

OBDomesticVRPInitiation

Name Path Definition Type
DebtorAccount (0..1) DebtorAccount Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction. OBCashAccountDebtorWithName
UltimateDebtor (0..1) UltimateDebtor Ultimate party that owes an amount of money to the (ultimate) creditor. OBUltimateDebtor1
CreditorAccount (0..1) CreditorAccount Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. OBCashAccountCreditor3
CreditorPostalAddress CreditorPostalAddress Information that locates and identifies a specific address, as defined by postal services or in free format text. OBPostalAddress7
UltimateCreditor (0..1) UltimateCreditor Ultimate party to which an amount of money is due. OBUltimateCreditor1
RemittanceInformation (0..1) RemittanceInformation Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system. OBRemittanceInformation2
RegulatoryReporting (0..10) RegulatoryReporting Information needed due to regulatory and statutory requirements. OBRegulatoryReporting1

# OBDomesticVRPControlParameters

The VRP consent is a common class used in domestic-payment-consents requests and responses

OBDomesticVRPControlParameters

Name Path Definition Type
ValidFromDateTime (0..1) ValidFromDateTime Start date time for which the consent remains valid.
The time element of the date should be disregarded in computing the date range and pro-rating.
ISODateTime
ValidToDateTime (0..1) ValidToDateTime End date time for which the consent remains valid.
The time element of the date should be disregarded in computing the date range and pro-rating.
ISODateTime
MaximumIndividualAmount (1..1) ControlParameters. MaximumIndividualAmount Maximum amount that can be specified in a payment instruction under this VRP consent ActiveOrHistoricCurrencyAndAmount
Amount (1..1) ControlParameters. MaximumIndividualAmount. Amount A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
Currency (1..1) ControlParameters. MaximumIndividualAmount. 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
PeriodicLimits (1..*) 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
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.
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
VRPType (1..*) ControlParameters. VRPType The types of payments that can be made under this VRP consent. This can be used to indicate whether this include sweeping payment or other ecommerce payments. OBVRPConsentType - Namespaced Enumeration
PSUAuthenticationMethods (1..*) ControlParameters. PSUAuthenticationMethods Indicates that the PSU authentication methods supported. OBVRPAuthenticationMethods - Namespaced Enumeration
PSUInteractionTypes (0..*) ControlParameters. PSUInteractionTypes Indicates interaction type, currently if customer is present or not present. If not provided the default is "OffSession" (the customer is not present) when the individual VRP payment is made. OBVRPInteractionTypes
SupplementaryData (0..1) ControlParameters. SupplementaryData Additional information that can not be captured in the structured fields and/or any other specific block *

# Examples of Periodic Limits

# Example 1

// 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
# Example 2
// 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
# Example 3
// 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
# Example 4
// 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

# OBRisk1

The Risk block is a common class used in requests and responses

OBRisk1

# Data Dictionary
Name Occurrence XPath EnhancedDefinition Class Codes Pattern
OBRisk1 OBRisk1 The Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Payments. OBRisk1
PaymentContextCode 0..1 OBRisk1/PaymentContextCode Specifies the payment context Specifies the payment context For a full list of enumeration values refer to OB_Internal_CodeSethere (opens new window). OBInternalPaymentContext1Code
CategoryPurposeCode 0..1 OBRisk1/CategoryPurposeCode For a full list of enumeration values refer to OB_EXternal_CodeSethere (opens new window). ExternalCategoryPurpose1Code
MerchantCategoryCode 0..1 OBRisk1/MerchantCategoryCode Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction. Min3Max4Text
MerchantCustomerIdentification 0..1 OBRisk1/MerchantCustomerIdentification The unique customer identifier of the PSU with the merchant. Max70Text
ContractPresentIndicator 0..1 OBRisk1/ContractPresentIndicator Indicates if Payee has a contractual relationship with the PISP. Boolean
BeneficiaryPrepopulatedIndicator 0..1 OBRisk1/BeneficiaryPrepopulatedIndicator Indicates if PISP has immutably prepopulated payment details in for the PSU. Boolean
PaymentPurposeCode 0..1 OBRisk1/PaymentPurposeCode For a full description see ExternalPurpose1Code here (opens new window) For a full list of enumeration values refer to External_CodeSet [here] ExternalPurpose1Code
BeneficiaryAccountType 0..1 OBRisk1/BeneficiaryAccountType To be provided if the AccountType is known. For a full list of enumeration values refer to OB_Internal_CodeSethere (opens new window). OBInternalExtendedAccountType1Code
DeliveryAddress 0..1 OBRisk1/DeliveryAddress Information that locates and identifies a specific address, as defined by postal services or in free format text. OBPostalAddress7

# OBDomesticVRPConsentRequest

OBDomesticVRPConsentRequest

Name Path Definition Type
Data (1..1) Data
Data. ReadRefundAccount (0..1) Data. ReadRefundAccount Indicates whether the RefundAccount object should be included in the response Yes No
ControlParameters (1..1) Data. ControlParameters The control parameters under which this VRP must operate OBDomesticVRPControlParameters
Initiation (1..1) Data. Initiation The parameters of the VRP consent that should remain unchanged for each payment under this VRP OBDomesticVRPInitiation
Risk (1..1) Risk The consent payload is sent by the initiating party to the ASPSP. It is used to request a consent to move funds from the debtor account to a creditor. OBRisk1

# OBDomesticVRPConsentResponse

OBDomesticVRPConsentResponse

Name Path Definition Type
Data (1..1) Data
ConsentId (1..1) Data. ConsentId Unique identification as assigned by the ASPSP to uniquely identify the consent resource. Max128Text
ReadRefundAccount (0..1) Data. ReadRefundAccount Indicates whether the RefundAccount object should be included in the response Yes No
CreationDateTime (1..1) Data. CreationDateTime Date and time at which the resource was created. ISODateTime
Status (1..1) Data. Status Specifies the status of resource in code form. For a full list of values see OBInternalConsentStatus1Code here (opens new window)
StatusUpdateDateTime (1..1) Data. StatusUpdateDateTime Date and time at which the resource status was updated. ISODateTime
StatusReason (0..*) Data. StatusReason An array of StatusReasonCode OBStatusReason
StatusReasonCode (0..1) Data. StatusReason. StatusReasonCode Specifies the status reason in a code form. For a full description see OB_Internal_CodeSet here (opens new window). OBExternalStatusReason1Code
StatusReasonDescription (0..1) Data. StatusReason. StatusReasonDescription Description supporting the StatusReasonCode. Max500text
Path (0..1) Data. StatusReason. Path Path is optional but relevant when the status reason refers to an object/field and hence conditional to provide JSON path. Max500Text
ControlParameters (1..1) Data. ControlParameters The control parameters under which this VRP must operate OBDomesticVRPControlParameters
Initiation (1..1) Data. Initiation The parameters of the VRP consent that should remain unchanged for each payment under this VRP OBDomesticVRPInitiation
DebtorAccount (0..1) Data.DebtorAccount The DebtorAccount details as specified by the PSU when account selection happens at the ASPSP.

Note: The details must be provided in the consent response (OBDomesticVRPConsentResponse) by the ASPSP to enable the PISP to associate it with future VRP payments that are made using the VRP Consent.
OBCashAccountDebtorWithName
Risk (1..1) Risk The consent payload is sent by the initiating party to the ASPSP. It is used to request a consent to move funds from the debtor account to a creditor. OBRisk1

# OBVRPFundsConfirmationRequest

The OBVRPFundsConfirmationRequest object must be used to request funds availability for a specific amount in the Debtor Account included in the VRP consents.

OBVRPFundsConfirmationRequest

Name Path Definition Type
Data (1..1) Data
ConsentId (1..1) Data. ConsentId Unique identification as assigned by the ASPSP to uniquely identify the funds confirmation consent resource. Max128Text
Reference (0..1) Data. Reference Unique reference, as assigned by the PISP, to unambiguously refer to the request related to the payment transaction. This must be the same value as the Reference field in the consent. Max35Text
InstructedAmount (1..1) Data. InstructedAmount Amount of money to be confirmed as available funds in the debtor account. Contains an Amount and a Currency. OBActiveOrHistoricCurrencyAndAmount
Amount (1..1) Data. InstructedAmount. Amount A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
Currency (1..1) Data. InstructedAmount. 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 ^[A-Z]{3,3}$

# OBVRPFundsConfirmationResponse

The OBVRPFundsConfirmationResponse object will be used for a response to a call to:

  • POST /domestic-vrp-consents/{ConsentId}/funds-confirmation

OBVRPFundsConfirmationResponse

The confirmation of funds response contains the result of a funds availability check.

Name Path Definition Type
Data (1..1) Data
FundsConfirmationId (1..1) Data. FundsConfirmationId Unique identification as assigned by the ASPSP to uniquely identify the funds confirmation resource. Max40Text
ConsentId (1..1) Data. ConsentId Unique identification as assigned by the ASPSP to uniquely identify the funds confirmation consent resource. Max128Text
CreationDateTime (1..1) Data. CreationDateTime Date and time at which the resource was created. ISODateTime
Reference (0..1) Data. Reference Unique reference, as assigned by the PISP, to unambiguously refer to the request related to the payment transaction. Max35Text
FundsAvailableResult (1..1) Data. FundsAvailableResult Result of a funds availability check. OBPAFundsAvailableResult1
FundsAvailableDateTime (1..1) Data. FundsAvailableResult. FundsAvailableDateTime Date and time at which the funds availability check was generated. ISODateTime
FundsAvailable (1..1) Data. FundsAvailableResult. FundsAvailable Availaility result, clearly indicating the availability of funds given the Amount in the request. Available NotAvailable
InstructedAmount (1..1) Data. InstructedAmount Amount of money to be confirmed as available funds in the debtor account. Contains an Amount and a Currency. OBActiveOrHistoricCurrencyAndAmount
Amount (1..1) Data. InstructedAmount. Amount A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
Currency (1..1) Data. InstructedAmount. 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

# Usage Examples

See Usage Examples