# Exchange the PSU Authorization for Access Consent source: https://developer.mastercard.com/open-banking-connect/documentation/aisfeatures/exchange-psu-consent/index.md ## Request overview {#request-overview} The goal of this request is to exchange the Payment Service User (PSU) authorization with the Account Servicing Payment Service Provider (ASPSP) for account access consent, which a TPP can use to access the account data. For more information, see [Account Information Consent Request](https://developer.mastercard.com/open-banking-connect/documentation/aisfeatures/account-information-consent/index.md). ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |-----------------------------------|------------|------------------|-------------------------------------------------------------------| | /accounts/consents/authorizations | `POST` | All | Exchanges the PSU authorization string for account access consent | The following sequence diagram shows the flow for exchanging the PSU authorization string for account access consent. Diagram exchange_consent ## Request scenario {#request-scenario} API Reference: `POST /accounts/consents/authorizations` #### 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 | 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 | String | Free field that allows for the addition of information that can be referenced for future use | 36 UUID 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 UUID 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 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 | | `merchant` | Collect merchant data for reporting purposes | MC | Merchant data used for reporting or reconciliation purpose | O | 0..1 | Object | Set of elements used to define the merchant details | N/A | | `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). 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 | 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 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}$` | | `consentRequestId` | Unique identification as assigned by the TPP to uniquely identify the consent request. | TPP | This element could be used for consent request- response tracking | M | 1..1 | String | Request consent identification | 1-256 | | `consentId` | A unique reference to the account information consent stored by the ASPSP. This is required to enable subsequent account information requests related to the consent (for example, to request account or transaction details) | TPP | Pass this value as part of the account information requests related to the consent. | M | 1..1 | String | A unique reference to the account information 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 | | `signatureStatus` | OBC validates the signature in the authorization code for CMA9 API standard ASPSP. If the signature is valid, then the request is processed and the response includes the successful status, otherwise the TPP will receive back notification of failed signature validation. | TPP | This element can be used to check TPP signature validation status | O | 0..1 | Enum | Status of validation of ASPSP's signature present in authorization code that TPP included in the request for credit transfer (furure use) | Enum: `VALID`, `UNKNOWN`, `UNSIGNED`, `NONCOMPLIANT` | ## 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** | |-------------------------------------------------------------|---------------------|----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "ASPSP's signature didn't pass validation. Result code: %s" | `INVALID_SIGNATURE` | The signature of ASPSP that was provided in the authorization code of the request couldn't be validated. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | Typically occurs because the signature of the ASPSP in the authorization string didn't pass one or multiple validations. This can be as a result of a modified redirect URL by the PSU, and expired signature, or other reasons. | Your request didn't get sent to ASPSP since the signature of the ASPSP in authorization code failed validation. Next steps depend on the result code in error message: · `revoked` -- The ASPSP revoked the signature certificate used. · `expired` - signature certificate has expired.Re-initiate payment. · `unknown` - signature certificate couldn't be identified. Reinitiate payment or contact support for more details. · `unsigned` - signature certificate is missing. Reinitiate payment or contact support for more details. · `noncompliant` - signature certificate is of an unexpected format. Contact support for more details. If you think you should be able to use the specified value, contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INVALID_SIGNATURE", "Description": "ASPSP's signature didn't pass validation. Result code: expired", "Details": "path[0]=/requestInfo/authorization" } ] } } ``` | **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** | |------------------------------------|-------------------------|-----------------------------------------------------------------------------------------|-----------------------|-------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | Authorization code used or expired | `INVALID_AUTHORIZATION` | TPP receives error response indicating that authorization code sent is used or expired. | | Error returned by ASPSP to indicate that the authorization string was either used previously or is expired. | Initiate the AIS consent request again and make sure the authorization string is exchanged within 1 minute after receiving it so it doesn't expire. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": "INVALID_AUTHORIZATION", "Description": "Authorization code used or expired", "Recoverable": false } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-------------------------------|-------------------------|---------------------------------------------------------------------------------|-----------------------|-------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------| | Authorization code is invalid | `INVALID_AUTHORIZATION` | TPP receives error response indicating that authorization code sent is invalid. | | Error returned by ASPSP to indicate that the authorization string is invalid. | Initiate the AIS consent request again and make sure the authorization string is correct. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": "INVALID_AUTHORIZATION", "Description": "Authorization code is invalid", "Recoverable": false } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-------------------------------|------------------|------------------------------------------|-----------------------|--------------------------------------------------------------|-------------------------------------------------------------------------------------------| | Authorization code is expired | `PROVIDER_ERROR` | The authorization code sent has expired. | | Typically occurs because the authorization code has expired. | Initiate the AIS consent request again and make sure the authorization string is correct. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": "PROVIDER_ERROR", "Description": "Authorization code is expired" } ] } } ```