# Exchange PSU authorization for VRP Access Consent source: https://developer.mastercard.com/open-banking-connect/documentation/pisfeatures/exchange-psu-authorization-for-vrp-access-consent-request/index.md ## Request overview {#request-overview} The goal of this request is to create an exchange PSU authorization for VRP Access Consent request and receive a Consent Id. ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |-------------------------------------------------|------------|-------------------------------------------------|-------------------------------------------------------------------------------------------| | /payments/domestic-vrps/consents/authorizations | `POST` | CMA9 (restricted to specific ASPSPs and TPPs\*) | Exchange PSU authorization for access consent, which can be used by TPP to initiate VRPs. | \*UK only. Available on subscription. The following sequence diagram shows the flows for an Exchange PSU authorization for VRP access consent request. Diagram exchange_psu_auth_for_vrp_access_consent ## Request scenario {#request-scenario} API Reference: `POST /payments/domestic-vrps/consents/authorizations` #### Request header {#request-header} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | |------------------------|---------------------------------------|-----------------|----------------------------------------------------------------------|---------------|------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `X-Mc-Idempotency-Key` | Is used to enable request idempotency | ASPSP | Should be used to ensure that requests are not rejected as duplicate | O | 0..1 | String | Required to enable idempotency for the request. If not provided, unique value will be generated and sent to the bank. Example: c0ba8bf3-ef1a-419f-87a3-28a1b2e6da96 | #### 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 | 36 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 | 36 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 Required when isLivePsuRequest=true. | 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 | 1-256 | | `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 | | `authorization` | Authorization data received from associated ASPSP | MC | Authorization data is used to exchange it for access consent | M | 1..1 | String | The authorization data received after PSU has authorized the consent | 1-5000 | 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 | | `consentRequestId` | Unique identification as assigned by the TPP to uniquely identify the consent request | TPP | This element could be used for request-response tracking | M | 1..1 | String | Request consent identification | 1-256 | | `consentId` | Unique reference to the account information consent stored by the ASPSP. This is required to enable VRP initiation requests related to the consent | TPP | This is used to enable VRP initiation requests related to the consent | M | 1..1 | String | A unique reference to the payment initiation consent stored by the ASPSP. | 1-256 | | `consentStatus` | Specifies the status of the consent | TPP | Status of the consent resource | O | 0..1 | String | Specifies consent status e.g. of banks statuses: Authorised, AwaitingAuthorisation, Rejected, Revoked, Expired | 1-50 | | `originalConsentStatus` | Specifies the status of the consent. Value returned by ASPSP | TPP | Could be used to support in a dispute | O | O..1 | String | Original consent status as returned by the ASPSP | 1-50 | ## 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" } ] } } ```