# Get Raw Consent source: https://developer.mastercard.com/open-banking-connect/documentation/pisfeatures/pis-get-raw-consent/index.md ## Request overview {#request-overview} The goal of this request is to retrieve, based on the `consentId` previously obtained, the original consent information. This flow assumes the Payment Service User (PSU) has already consented to this access. For more information, see [Payment Initiation Consent Request](https://developer.mastercard.com/open-banking-connect/documentation/pisfeatures/payment-initiation-consent-request/index.md). ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |-------------------------|------------|------------------|-----------------------------------------------------------------------------------------------| | /payments/consents/raw | `POST` | CMA9 | Returns original raw consent given by the Account Servicing Payment Service Provider (ASPSP). | The following sequence diagram shows the flows for getting raw consent. Diagram raw_consent_pis ## Request scenario {#request-scenario} API Reference: `POST /payments/consents/raw` #### Request header {#request-header} N/A #### 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 | - | | `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 | String UUID | Free field that allows for the addition of information that can be referenced for future use | 36 | | `aspspId` | ID of a financial institution servicing the Accounts of the PSU | ASPSP | Identification of ASPSP. | M | 1..1 | UUID | Specifies the identification code of a financial institution which holds PSU accounts. | 36 | | `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 pattern: `(^(([0-9]` \| `[1-9][0-9]` \| `1[0-9]{2}` \| `2[0-4][0-9]` \| `25[0-5])\.){3}([0-9]` \| `[1-9][0-9]` \| `1[0-9]{2}` \| `2[0-4][0-9]` \| `25[0-5])$)` \| `(^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}` \| `([0-9a-fA-F]{1,4}:){1,7}:` \| `([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}` \| `([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}` \| `([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}` \| `([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}` \| `([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}` \| `[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})` \| `:((:[0-9a-fA-F]{1,4}){1,7}` \| `:)` \| `fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}` \| `::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9])` \| `([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9]))$)` | | `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 | | `consentId` | A unique reference to the payment initiation consent stored by the ASPSP. This is required to enable subsequent calls related to the payment (for example,. to request payment status details) | ASPSP | Pass this value as part of the payment status requests related to the consent. | M | 1..1 | String | A unique reference to the payment initiation consent stored by the ASPSP. Please note that this is not the original value generated by the ASPSP but a generated 'proxy' value related to that. | 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 | 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). For specific error codes for this feature see **Feature specific error codes** below. #### 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 | String UUID | Original `xRequestId` given by the client on request | 36 `^[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}$` | | `rawConsent` | Returns raw consent data from associated ASPSP | TPP | Raw consent data could be used to extract additional information sent by ASPSP | O | 0..1 | String | Raw consent data received from ASPSP and encoded Base64. | | #### Response example {#response-example} An example of a raw consent response received by TPPs can be seen below. ```json { "originalRequestInfo": { "xRequestId": "522fc1c4-3a16-4d66-a8f7-25b4555a79a7" }, "rawConsent": "eyJEYXRhIjp7IkNvbnNlbnRJZCI6ImFhYy02Njc5Y2I5My05MTg4LTQ4YTQtYTdhMy05ZGY1ZjU1YjhjOWQiLCJDcmVhdGlvbkRhdGVUaW1lIjoiMjAyMC0xMS0xN1QxMDoyMzoyNC41OTJaIiwiU3RhdHVzIjoiQXV0aG9yaXNlZCIsIlN0YXR1c1VwZGF0ZURhdGVUaW1lIjoiMjAyMC0xMS0xN1QxMDoyMzo0My4wNTJaIiwiUGVybWlzc2lvbnMiOlsiUmVhZEFjY291bnRzRGV0YWlsIl19LCJSaXNrIjp7fSwiTWV0YSI6e30sIkxpbmtzIjp7IlNlbGYiOiJodHRwczovL29iMTktcnMxLm8zYmFuay5jby51azo0NTAxL29wZW4tYmFua2luZy92My4xL2Fpc3AvYWNjb3VudC1hY2Nlc3MtY29uc2VudHMvYWFjLTY2NzljYjkzLTkxODgtNDhhNC1hN2EzLTlkZjVmNTViOGM5ZCJ9fQ==" } ``` The value of the rawConsent field is base64 encoded and after decoding the TPP will be able to obtain data similar to the following: ```json {"Data":{"ConsentId":"aac-6679cb93-9188-48a4-a7a3-9df5f55b8c9d","CreationDateTime":"2020-11-17T10:23:24.592Z","Status":"Authorised","StatusUpdateDateTime":"2020-11-17T10:23:43.052Z","Permissions":["ReadAccountsDetail"]},"Risk":{},"Meta":{},"Links":{"Self":"https://ob19-rs1.o3bank.co.uk:4501/open-banking/v3.1/aisp/account-access-consents/aac-6679cb93-9188-48a4-a7a3-9df5f55b8c9d"}} ``` ## 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** | |---------------------------------------------------|-----------------|------------------------------------------------|-----------------------|-------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "This feature is unavailable for this Provider."" | `NOT_ALLOWED` | This feature is unavailable for this Provider. | n/a | Typically occurs because the authorization happened through DEFAULT flow and TPP has requested Raw Consent. | Use CMA9_DIRECT flow to be able to Get Raw Consent. Some ASPSPs may not return the Raw consent. If you need to use CMA9_DIRECT flow then contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "NOT_ALLOWED", "Description": "This feature is unavailable for this Provider. ", } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------------------------|-----------------|------------------------------------------------------|-----------------------|------------------------------------------------------------------------------------------------|-------------------------------------| | "Access Token associated with the Request has expired" | `INVALID_TOKEN` | Access Token associated with the Request has expired | n/a | Typically occurs when the consent that the TPP has previously obtained from a PSU has expired. | PSU needs to provide a new consent. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " INVALID_TOKEN ", "Description": "Access Token associated with the Request has expired" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------------------------------------|-----------------|----------------------------------------------------------|-----------------------|-------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Access Token associated with the Request is invalid or has been revoked" | `INVALID_TOKEN` | The consent id used in the request is invalid or revoked | n/a | Typically occurs when the consent id is invalid or revoked. | Ensure a valid consent id is used in the request. If you think the specified consent id is valid please contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INVALID_TOKEN", "Description": "Access Token associated with the Request is invalid or has been revoked" } ] } } ``` | **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\]=\<\\path to the element that failed the validation\>;" 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. | Provide 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" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------|------------------|-----------------------------------------------------------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------| | "Provided account is invalid or unlinked from the consent" | `PROVIDER_ERROR` | Provided account is invalid or unlinked from the consent. | N/A | Typically occurs when an invalid account id is included in the request, or when the account id was unlinked from the consent due to various issues with previous requests using the same consent. | Ensure a valid account id is included or ask for a fresh consent from the PSU and include in the request. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " PROVIDER_ERROR ", "Description": "Provided account is invalid or unlinked from the consent" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------------------|------------------|---------------------------------------------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "ASPSP limit for unattended requests was exceeded" | `PROVIDER_ERROR` | ASPSP limit for unattended requests was exceeded. | N/A | Typically occurs when ASPSP limit (usually set to 4 requests) for unattended requests (without PSU details) is exceeded. | Please ensure that PSU is online during AIS requests, include PSU details (isLivePsuRequest , psuIPAddress and psuAgent), or try submitting requests the following day. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " PROVIDER_ERROR ", "Description": "ASPSP limit for unattended requests was exceeded" } ] } } ```