# Domestic VRP consents - v3.1.9
- Overview
- Endpoints
- State Model - VRP consents
- Data Model
- Usage Examples
# 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 |
# 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 AwaitingAuthorisation.
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.
# 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 Authorised.
If resource has any other Status, the ASPSP must respond with a 400 (Bad Request) and a UK.OBIE.Resource.InvalidConsentStatus error code.
# State Model - VRP consents
The state model for the VRP consents resource follows the generic consent state model. However, it does not use the Consumed status.
All domestic-vrp-consents start off with a state of AwaitingAuthorisation
Once the PSU authorises the resource - the state of the resource will be set to Authorised.
If the PSU rejects the consent, the state will be set to Rejected.
The available status codes for the VRP consents resource are:
- AwaitingAuthorisation
- Rejected
- Authorised
The definitions for the Status:
| Status | Status Description | |
|---|---|---|
| 1 | AwaitingAuthorisation | The consent resource is awaiting PSU authorisation. |
| 2 | Rejected | The consent resource has been rejected. |
| 3 | Authorised | The consent resource has been successfully authorised. |
| 4 | Revoked | The consent resource has been revoked by the PSU, via ASPSP's online channel. |
# Data Model
The data dictionary section gives the detail on the payload content for the VRP consent API flows.
# 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 OBExternalAccountIdentification4Code |
| 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 |
# 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 |
# OBBranchAndFinancialInstitutionIdentification6
| Name | Path | Definition | Type |
|---|---|---|---|
| SchemeName (0..1) | SchemeName | Name of the identification scheme, in a coded form as published in an external list. | OBExternalFinancialInstitutionIdentification4Code |
| 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 |
| PostalAddress (0..1) | PostalAddress | Information that locates and identifies a specific address, as defined by postal services. | OBPostalAddress6 |
| AddressType (0..1) | PostalAddress. AddressType | Identifies the nature of the postal address. | OBAddressTypeCode |
| Department (0..1) | PostalAddress. Department | Identification of a division of a large organisation or building. | Max70Text |
| SubDepartment (0..1) | PostalAddress. SubDepartment | Identification of a sub-division of a large organisation or building. | Max70Text |
| StreetName (0..1) | PostalAddress. StreetName | Name of a street or thoroughfare. | Max70Text |
| BuildingNumber (0..1) | PostalAddress. BuildingNumber | Number that identifies the position of a building on a street. | Max16Text |
| PostCode (0..1) | PostalAddress. PostCode | Identifier consisting of a group of letters and. or numbers that is added to a postal address to assist the sorting of mail. | Max16Text |
| TownName (0..1) | PostalAddress. TownName | Name of a built-up area, with defined boundaries, and a local government. | Max35Text |
| CountrySubDivision (0..1) | PostalAddress. CountrySubDivision | Identifies a subdivision of a country such as state, region, county. | Max35Text |
| Country (0..1) | PostalAddress. Country | Nation with its own government. | CountryCode |
| AddressLine (0..7) | PostalAddress. AddressLine | Information that locates and identifies a specific address, as defined by postal services, presented in free format text. | Max70Text |
# 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 |
| CreditorAgent (0..1) | CreditorAgent | Financial institution servicing an account for the creditor. | OBBranchAndFinancialInstitutionIdentification6 |
| 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 |
| 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. | Max140Text |
| Unstructured (0..1) | RemittanceInformation. Unstructured | 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 | OBRemittanceInformation1 |
| Reference (0..1) | RemittanceInformation. Reference | Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction. Usage: If available, the initiating party should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money. If the business context requires the use of a creditor reference or a payment remit identification, and only one identifier can be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be quoted in the end-to-end transaction identification. | Max35Text |
# OBDomesticVRPControlParameters
The VRP consent is a common class used in domestic-payment-consents requests and responses
| 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 (0..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 (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 | |
| 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..M) | ControlParameters. PSUAuthenticationMethods | Indicates that the PSU authentication methods supported. | OBVRPAuthenticationMethods - Namespaced Enumeration |
| 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": {
"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": {
"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": {
"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": {
"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
| Name | Path | Definition | Type |
|---|---|---|---|
| PaymentContextCode (0..1) | PaymentContextCode | Specifies the payment context | OBExternalPaymentContext1Code: BillPayment EcommerceGoods EcommerceServices Other PartyToParty |
| MerchantCategoryCode (0..1) | 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) | MerchantCustomerIdentification | The unique customer identifier of the PSU with the merchant. | Max70Text |
| DeliveryAddress (0..1) | DeliveryAddress | Information that locates and identifies a specific address, as defined by postal services or in free format text. | PostalAddress18 |
| AddressLine (0..2) | DeliveryAddress. AddressLine | Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text. | Max70Text |
| StreetName (0..1) | DeliveryAddress. StreetName | Name of a street or thoroughfare. | Max70Text |
| BuildingNumber (0..1) | DeliveryAddress. BuildingNumber | Number that identifies the position of a building on a street. | Max16Text |
| PostCode (0..1) | DeliveryAddress. PostCode | Identifier consisting of a group of letters and. or numbers that is added to a postal address to assist the sorting of mail. | Max16Text |
| TownName (1..1) | DeliveryAddress. TownName | Name of a built-up area, with defined boundaries, and a local government. | Max35Text |
| CountrySubDivision (0..1) | DeliveryAddress. CountrySubDivision | Identifies a subdivision of a country, for instance state, region, county. | Max35Text |
| Country (1..1) | DeliveryAddress. Country | Nation with its own government, occupying a particular territory. | ^[A-Z]{2,2}$ |
# OBDomesticVRPConsentRequest
| Name | Path | Definition | Type |
|---|---|---|---|
| Data (0..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. | OBRisk |
# 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 |
| Data. 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. | Authorised AwaitingAuthorisation Rejected Revoked |
| StatusUpdateDateTime (1..1) | Data. StatusUpdateDateTime | Date and time at which the resource status was updated. | ISODateTime |
| 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 approved DebtorAccount that the payment can be made from. THe value must be populated for GET responses once the consent is approved. | 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. | OBRisk |
# OBVRPFundsConfirmationRequest
The OBVRPFundsConfirmationRequest object must be used to request funds availability for a specific amount in the Debtor Account included in the VRP consents.
| 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 (1..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
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 (1..1) | Data. Reference | Unique reference, as assigned by the CBPII, 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