# Get VRP Consent Details source: https://developer.mastercard.com/open-banking-connect/documentation/pisfeatures/get-vrp-consent-details-request/index.md ## Request overview {#request-overview} The goal of this request is to return VRP consent details. ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |--------------------------------------------------|------------|-------------------------------------------------|-------------------------------------------------------| | /payments/domestic-vrps/consents/consent-details | `POST` | CMA9 (restricted to specific ASPSPs and TPPs\*) | Retrieve the details of a VRP consent from the ASPSP. | \*UK only. Available on subscription. The following sequence diagram shows the flows for a Get VRP Consent Details request. Diagram vrp_consent_details ## Request scenario {#request-scenario} API Reference: `POST /payments/domestic-vrps/consents/consent-details` #### Request body {#request-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|------------------|----------|-------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------| | `requestInfo` | Includes information about request being processed | MC | This element encapsulates all request information sent to the API Service | M | 1..1 | Object | Set of elements used to define the request details | N/A | | `xRequestId` | ID of the request, unique to the call, as determined by the TPP | TPP | A memorable ID could be used to support in a dispute | M | 1..1 | UUID | Free field that allows for the addition of information that can be referenced for future use | pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` | | `aspspId` | ID of a financial institution servicing the Accounts of the PSU | ASPSP | Identification of ASPSP. | M | 1..1 | String | This element is used to specify the identification code of a financial institution which holds PSU accounts | pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` | | `isLivePsuRequest` | Indicates if PSU actively initiated request | ASPSP | Type of PSU request | O | 0..1 | Boolean | PSU request type | Boolean: true or false | | `psuIPAddress` | The forwarded IP address field consists of the corresponding HTTP request IP address field between PSU and TPP. | ASPSP | It shall be contained only if the PSU actively initiated this request | C | 0..1 | String | IP address of PSU's terminal device | 1-256 Required when isLivePsuRequest=true | | `psuAgent` | Indicates the user-agent for the PSU. If the PSU is using the TPP's mobile app, make sure the mobile app user-agent string is different than browser-based user-agent strings. | ASPSP | If user-agent is supplied to ASPSP, then this information can be used by ASPSP's security mechanisms. To avoid rejections, it is recommended to include this field when providing isLivePsuRequest and psuIPAddress. | O | 0..1 | String | PSU's browser agent details | 1-256 | | `merchant` | Collect merchant data for reporting purposes | MC | Merchant data used for reporting or reconciliation purposes | O | 0..1 | Object | Set of elements used to define the merchant details | | | `id` | Merchant identification code to identify the merchant | MC | Unique Merchant identifier per TPP, which could be used for reporting/reconciliation purposes | M | 1..1 | String | Field is available for TPPs to enable capturing of a merchant ID | 1-256 | | `name` | Merchant name to identify the merchant | MC | Name of merchant | M | 1..1 | String | Field is available for TPPs to enable capturing of a merchant name | 1-256 | | `consentId` | A unique reference to the account information consent stored by the ASPSP. | ASPSP | Pass this value as part of the variable recurrent payment initiation request. | M | 1..1 | String | A unique reference to the account information consent stored by the ASPSP. | 1-256 | Tip: For an explanation of notations used, refer to **Open Banking General FAQ** in our [Frequently Asked Questions](https://developer.mastercard.com/open-banking-connect/documentation/frequently-asked-questions/index.md) section. ### Response -- Success {#response--success} HTTP Response Code = 200, OK Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). #### Response header {#response-header} N/A #### Response body {#response-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------------------|---------------|------------------|--------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------| | `originalRequestInfo` | Returns original request information to the TPP | MC | This object contains original request information | M | 1..1 | Object | Original request information received from the TPP | N/A | | `xRequestId` | A memorable ID which could be used to support in a dispute | TPP | This element could be used for request-response tracking | M | 1..1 | UUID | Original `xRequestId` given by the client on request | 36 | | `consent` | VRP Consent | ASPSP | VRP consent details are returned within the object | M | 1..1 | Object | Set of elements used to return VRP consent details | N/A | | `controlParameters` | This object is used to submit VRP consent control parameters to the ASPSP | ASPSP | VRP consent control parameters are provided within this object | M | 1..1 | Object | Set of elements used to define VRP consent control parameters | N/A | | `vrpTypes` | Specifies the types of payments that can be made under this VRP consent | ASPSP | The type of Variable Recurring Payment is returned in this field | O | O..1 | String Enum: `['SWEEPING']` | Specified the types of payments that can be made under this VRP consent, e.g. sweeping payment, other ecommerce payments. | 1-256 | | `validFrom` | The first date of execution for a VRP payment | ASPSP | This element is used to specify the date for the first payment | O | O..1 | ISODate | Start date by which a consent starts to be valid. | $date-time | | `validTo` | The last applicable day of execution for a given VRP. | ASPSP | This element is used to specify payment last execution date | O | O..1 | ISODate | End date for consent validity | $date-time | | `maximalIndividualAmount` | This object is used to set details for max amount per VRP payment | ASPSP | Currency and amount details included in this object to specify the max amount for a VRP payment | M | 1..1 | Object | Structure aiming to embed maximal amount and currency of each VRP in currently defined series | N/A | | `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" | ASPSP | The currency of the amount used in the VRP | M | 1..1 | Enum: `["GBP"]` | Specifies the currency of the included amount | pattern: `^[A-Z]{3}$` | | `amount` | A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217 | ASPSP | This element is used to specify the amount of money to be processed for the VRP | M | 1..1 | Decimal | Maximal amount of money that can be moved between the debtor and creditor accounts | minimum: 0 | | `periodicLimits` | This object is used to return the details of the periodic limits for a VRP | ASPSP | Frequency details and max total VRP amount are returned in the details of the object | M | 1..\* | Object | Set of elements specifying amount and currency limit per specified frequency | N/A | | `frequency` | Frequency rule for VRPs | ASPSP | This element is used to specify the frequency of a VRP | M | 1..1 | Enum: \['Day', 'Week', 'Fortnight', 'Month', 'Half-year', 'Year'\] | Payment frequency -determines how often a variable recurring payment will be made. | 1-256 | | `frequencyAlignment` | The date by which the VRP is allowed to be initiated with the specified frequency | ASPSP | Is used to specify the alignment of the frequency rule | M | 1..1 | Enum: Consent, Calendar | The date by which the VRP is allowed to be initiated with the specified frequency | 1-256 | | `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". | ASPSP | The currency of the amount used in the VRP at the specified frequency | M | 1..1 | Enum: `["GBP"]` | Specifies the currency of the periodic amount | pattern: `^[A-Z]{3}$` | | `amount` | A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. | ASPSP | This element is used to specify the amount of money to be processed for the VRP per the specified frequency | M | 1..1 | Decimal | Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the TPP Maximal periodic amount of money that can be moved between the debtor and creditor accounts | Min:0 | | `creditorAccount` | Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the VRP payment transaction. | ASPSP | Specify account in a financial institution servicing the creditor | O | O..1 | Object | Set of elements used to define the creditor account details | N/A | | `schemeName` | Name of the identification scheme, in a coded form as published in an external list. | ASPSP | This field is used to identify the type of Identification used to identify an account. | M | 1..1 | String Example: 'UK.AccountNumber' | Account scheme name | 1-256 | | `identification` | Identification assigned by an institution to identify an account. This identification is known by the account owner. | ASPSP | This element is used to specify the account identification number | M | 1..1 | String | Account identification which can be used on payload-level to address specific accounts | 1-256 | | `creditorName` | Name by which a party is known, and which is usually used to identify that party. | ASPSP | This element is used to specify creditor name | O | 0..1 | String | Name by which a party is known, and which is usually used to identify that party. | 1-70 | | `remittanceInformationReference` | Reference information provided by the creditor to allow the identification of the underlying documents | ASPSP | Specify financial institution servicing an account for the creditor. | O | 0..1 | String | Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction | 1-256 | | `consentStatus` | Specifies the status of the consent | TPP | Status of the consent resource | O | 0..1 | String | Specifies consent status | 1-256 | | `creditorAgent` | Unambiguous identification of the financial institution of the creditor to which a credit entry will be posted as a result of the payment transaction | ASPSP | Specify financial institution servicing an account for the creditor | O | 0..1 | Object | Set of elements used to define the creditor agent details | N/A | | `clearingSystemIdentification` | Name of the identification scheme, in a coded form as published in an external list | ASPSP | This field is used to identify the type of identification used to identify an agent | M | 1..1 | String: Example: 'UK.SortCode' | Clearing system identification scheme | 1-256 | | `memberIdentification` | Code allocated to a financial institution by the ISO 9362 Registration Authority to identify the financial institution | ASPSP | This element is used to specify the financial institution identification code | M | 1..1 | String | Identification code to identify the financial institution | 1-256 | | `refundAgent` | Unambiguous identification of the financial institution of the debtor to which a debit entry will be made as a result of the transaction. | ASPSP | Specify financial institution servicing an account for the debtor | O | 0..1 | object | Set of elements used to define the debtor agent details | N/A | | `clearingSystemIdentification` | Code allocated to a financial institution by the ISO 9362 Registration Authority to identify the financial institution. | ASPSP | This element is used to specify the financial institution identification code. | O | 0..1 | Enum: Example: 'UK.SortCode' | Clearing system identification scheme | 1-256 | | `memberIdentification` | Code allocated to a financial institution by the ISO 9362 Registration Authority to identify the financial institution. | ASPSP | This element is used to specify the financial institution identification code. | O | 0..1 | String | Identification code to identify the financial institution. | 1-256 | | `refundAccount` | refundAccount object is available in the response only when PSU has provided consent to share account details with the TPP. It includes PSU's account details. | TPP | This element encapsulates refund account details | O | 0..1 | Object | Object encapsulating refund account details. | N/A | | `schemeName` | Name of the scheme, used to specify the account identification type. | TPP | Details received in this field can be used for creditor account details in the reversed payment | O | 0..1 | String | Account scheme name | Example values: UK.AccountNumber 1-256 | | `identification` | Account identification number. It can be used on payload-level to mention specific account. | TPP | This element encapsulates refund account details | O | 0..1 | Object | Account identification which can be used on payload-level to address specific accounts | 1-256 | | `name` | This field is used to send the name of debtor account owner. | TPP | The data from this field can be used in the creditorName field for refund payments. | O | 0..1 | Object | The account name is the name or names of the account owner(s) represented at an account level as it was assigned by the ASPSP. | 1-256 | ## Feature specific error codes {#feature-specific-error-codes} Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------------------------------------|-----------------|-----------------------------------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| | "Conditional field psuIPAddress is expected when isLivePsuRequest='true'" | `FORMAT_ERROR` | "IP address" field is mandatory if parameter "isLivePsuRequest"=true. | "path\[i\]=;" where i = 0, 1, 2, etc. for each element that failed the validation | Typically occurs because the TPP has provided in request "isLivePsuRequest"=true and didn't provide the IP address value. | Please include the IP address of PSU in the request when providing "isLivePsuRequest"=true. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Conditional field psuIPAddress is expected when isLivePsuRequest='true", "Details": "path[0]=/requestInfo/psuIPAddress" } ] } } ```